@north-light/crouter 0.3.231 → 0.3.232

package/dist/core/human/page-html-markdown.js

@@ -0,0 +1,260 @@
+/** An HTML page's document projected to markdown, so a terminal reader sees the
+ *  page's actual content instead of a placeholder line. HTML pages are authored
+ *  for a browser surface and carry no slots, so this is a reading projection
+ *  only — layout, styling, and scripting are dropped, and what survives is the
+ *  prose, headings, lists, links, code, and table cells the author wrote. */
+const DROPPED = new Set(['script', 'style', 'head', 'template', 'noscript', 'svg', 'iframe', 'object']);
+const BLOCK = new Set([
+    'address', 'article', 'aside', 'blockquote', 'details', 'dialog', 'div', 'dl', 'fieldset', 'figcaption', 'figure',
+    'footer', 'form', 'header', 'main', 'nav', 'p', 'section', 'summary', 'table', 'tbody', 'tfoot', 'thead', 'video',
+]);
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“' };
+const TAG = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<![^>]*>|<(\/?)([a-zA-Z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>])*?)\/?>/g;
+const ATTR = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+function decode(value) {
+    return value.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (whole, body) => {
+        if (body.startsWith('#')) {
+            const code = body[1] === 'x' || body[1] === 'X' ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+        }
+        return ENTITIES[body.toLowerCase()] ?? whole;
+    });
+}
+function attrsOf(source) {
+    const attrs = new Map();
+    for (const match of source.matchAll(ATTR))
+        attrs.set(match[1].toLowerCase(), decode(match[2] ?? match[3] ?? match[4] ?? ''));
+    return attrs;
+}
+function tokenize(document) {
+    const tokens = [];
+    let at = 0;
+    for (const match of document.matchAll(TAG)) {
+        if (match.index > at)
+            tokens.push({ kind: 'text', text: document.slice(at, match.index) });
+        at = match.index + match[0].length;
+        if (match[2] !== undefined)
+            tokens.push({ kind: 'tag', name: match[2].toLowerCase(), closing: match[1] === '/', selfClosing: match[0].endsWith('/>'), attrs: attrsOf(match[3] ?? '') });
+    }
+    if (at < document.length)
+        tokens.push({ kind: 'text', text: document.slice(at) });
+    return tokens;
+}
+/** Markdown's structural characters, escaped so authored prose reads as prose.
+ *  Mirrors the JSX projection's escaping so both dialects render alike. */
+function escapeText(value) {
+    return value.replace(/([\\`*_[\]<>#])/g, '\\$1');
+}
+class Sink {
+    buffers = [''];
+    write(text) { this.buffers[this.buffers.length - 1] += text; }
+    get top() { return this.buffers[this.buffers.length - 1]; }
+    set top(value) { this.buffers[this.buffers.length - 1] = value; }
+    push() { this.buffers.push(''); }
+    pop() { return this.buffers.length > 1 ? this.buffers.pop() : ''; }
+    get nested() { return this.buffers.length > 1; }
+    /** End the current line without opening a new block. */
+    line() {
+        this.top = this.top.replace(/[ \t]+$/, '');
+        if (this.top !== '' && !this.top.endsWith('\n'))
+            this.write('\n');
+    }
+    /** Separate what follows from what precedes by one blank line. */
+    block() {
+        this.top = this.top.replace(/[ \t\n]+$/, '');
+        if (this.top !== '')
+            this.write('\n\n');
+    }
+    done() { return this.buffers.join('').replace(/\n{3,}/g, '\n\n').replace(/[ \t]+\n/g, '\n').trim(); }
+}
+/** Project one authored HTML document to markdown. Never throws: a document
+ *  this cannot make sense of yields whatever text it did find, down to ''. */
+export function projectHtmlDocumentMarkdown(document) {
+    const sink = new Sink();
+    const lists = [];
+    const anchors = [];
+    const dropped = [];
+    let preDepth = 0;
+    let cellOpen = false;
+    let headerRow = false;
+    let rowCells = 0;
+    const indent = () => '  '.repeat(Math.max(0, lists.length - 1));
+    for (const token of tokenize(document)) {
+        if (token.kind === 'text') {
+            if (dropped.length > 0)
+                continue;
+            if (preDepth > 0) {
+                sink.write(token.text);
+                continue;
+            }
+            const text = decode(token.text).replace(/\s+/g, ' ');
+            if (text.trim() === '') {
+                if (/\s/.test(text))
+                    sink.write(' ');
+                continue;
+            }
+            sink.write(escapeText(text));
+            continue;
+        }
+        const { name, closing, attrs } = token;
+        // Unwinding to the matching open keeps one stray close tag from reopening
+        // the whole document, and one stray open from swallowing the rest of it.
+        if (DROPPED.has(name)) {
+            if (closing) {
+                const at = dropped.lastIndexOf(name);
+                if (at >= 0)
+                    dropped.length = at;
+            }
+            else if (!token.selfClosing)
+                dropped.push(name);
+            continue;
+        }
+        if (dropped.length > 0)
+            continue;
+        const heading = /^h([1-6])$/.exec(name);
+        if (heading !== null) {
+            sink.block();
+            if (!closing)
+                sink.write(`${'#'.repeat(Number(heading[1]))} `);
+            continue;
+        }
+        if (name === 'pre') {
+            if (closing) {
+                preDepth = Math.max(0, preDepth - 1);
+                sink.line();
+                sink.write('```');
+                sink.block();
+            }
+            else {
+                sink.block();
+                sink.write('```\n');
+                preDepth++;
+            }
+            continue;
+        }
+        if (name === 'br') {
+            sink.line();
+            continue;
+        }
+        if (name === 'hr') {
+            sink.block();
+            sink.write('---');
+            sink.block();
+            continue;
+        }
+        if (name === 'ul' || name === 'ol') {
+            if (closing)
+                lists.pop();
+            else {
+                sink.block();
+                lists.push({ ordered: name === 'ol', index: 0 });
+            }
+            if (closing)
+                sink.block();
+            continue;
+        }
+        if (name === 'li') {
+            if (closing)
+                continue;
+            const frame = lists[lists.length - 1];
+            sink.line();
+            if (frame === undefined)
+                sink.write('- ');
+            else {
+                frame.index++;
+                sink.write(`${indent()}${frame.ordered ? `${frame.index}. ` : '- '}`);
+            }
+            continue;
+        }
+        if (name === 'dt' || name === 'dd') {
+            sink.line();
+            if (!closing)
+                sink.write(name === 'dt' ? '' : '  ');
+            continue;
+        }
+        if (name === 'tr') {
+            if (closing) {
+                sink.write(rowCells > 0 ? ' |' : '');
+                if (headerRow && rowCells > 0) {
+                    sink.line();
+                    sink.write(`|${' --- |'.repeat(rowCells)}`);
+                }
+                sink.line();
+            }
+            else {
+                sink.line();
+                headerRow = false;
+                rowCells = 0;
+            }
+            continue;
+        }
+        if (name === 'td' || name === 'th') {
+            if (closing) {
+                if (!cellOpen)
+                    continue;
+                cellOpen = false;
+                sink.write(sink.pop().replace(/\s+/g, ' ').trim());
+            }
+            else {
+                if (name === 'th')
+                    headerRow = true;
+                rowCells++;
+                sink.write(rowCells === 1 ? '| ' : ' | ');
+                sink.push();
+                cellOpen = true;
+            }
+            continue;
+        }
+        if (name === 'a') {
+            // The label is captured rather than streamed, so a link with no text
+            // never leaves a bare `[](url)` behind.
+            if (closing) {
+                if (anchors.length === 0)
+                    continue;
+                const href = anchors.pop();
+                if (href === null)
+                    continue;
+                const label = sink.pop().replace(/\s+/g, ' ').trim();
+                if (label !== '')
+                    sink.write(`[${label}](${href})`);
+                continue;
+            }
+            const href = attrs.get('href');
+            const linkable = href !== undefined && href !== '' && !href.startsWith('#');
+            anchors.push(linkable ? href : null);
+            if (linkable)
+                sink.push();
+            continue;
+        }
+        if (name === 'code' && preDepth === 0) {
+            sink.write('`');
+            continue;
+        }
+        if (name === 'strong' || name === 'b') {
+            sink.write('**');
+            continue;
+        }
+        if (name === 'em' || name === 'i') {
+            sink.write('*');
+            continue;
+        }
+        if (name === 'img') {
+            const alt = attrs.get('alt');
+            if (alt !== undefined && alt !== '')
+                sink.write(escapeText(alt));
+            continue;
+        }
+        if (name === 'blockquote') {
+            sink.block();
+            if (!closing)
+                sink.write('> ');
+            continue;
+        }
+        if (BLOCK.has(name) && !VOID.has(name)) {
+            sink.block();
+            continue;
+        }
+    }
+    return sink.done();
+}

package/dist/core/memory/lint.d.ts

@@ -112,6 +112,21 @@ export interface MemoryLintStoreOptions {
  *  the identities its links resolve against are undetermined until migration
  *  declares the namespace. */
 export declare function lintMemoryStore(store: MemoryStoreDescriptor, options?: MemoryLintStoreOptions): MemoryLintResult;
+export interface MemoryLintDocumentOptions {
+    /** Canonical names a `[[link]]` or route may target. Omit to skip reference
+     *  checks — the caller pays for the corpus index only when the document
+     *  actually carries a reference to resolve. */
+    resolvable?: ReadonlySet<string>;
+    /** The store sits below the mounted project roots, so its boot entries are
+     *  inert. Omit when the document carries no boot entry: the rule cannot fire. */
+    nestedStore?: boolean;
+}
+/** Lint ONE document, by absolute path, in the store that holds it. Runs every
+ *  file-level rule the store sweep runs, and the store-level front-door rule
+ *  this one file can violate on its own. It does NOT run the rules that need
+ *  the whole store (canonical collisions, missing front-door coverage), so it
+ *  never replaces `crtr memory lint` — it catches what an author just typed. */
+export declare function lintMemoryDocument(store: MemoryStoreDescriptor, filePath: string, options?: MemoryLintDocumentOptions): MemoryLintResult;
 export interface MemoryLintTargetOptions {
     /** Whose view to lint. Default: the ambient process (cwd + CRTR_PROFILE_ID +
      *  CRTR_NODE_ID). */

package/dist/core/memory/lint.js

@@ -229,96 +229,19 @@ export function lintMemoryStore(store, options = {}) {
         if (relPath === '')
             continue;
         checked += 1;
-        let fm;
-        let body;
-        try {
-            ({ data: fm, body } = parseFrontmatterGeneric(readText(file)));
-        }
-        catch (e) {
-            add('error', 'yaml', file, `invalid YAML frontmatter: ${(e instanceof Error ? e.message : String(e)).split('\n')[0]}`);
-            continue;
-        }
-        if (NON_DOCUMENT_FILES.has(basename(file)))
-            continue;
-        documents += 1;
-        const isRootFile = localNameFromPath(relPath) === '';
-        const doc = docsByPath.get(file);
-        // A file the loader dropped (a root INDEX.md composing to the empty name)
-        // carries no canonical identity, but its frontmatter contract still holds —
-        // the field rules below run before the identity-dependent ones.
-        const named = doc === undefined ? {} : { name: doc.name };
-        const schemaError = lintSubstrateFrontmatter(fm);
-        if (schemaError !== null)
-            add('error', 'schema', file, schemaError, named);
-        if (fm !== null) {
-            const isRepositoryRootStore = isProjectStore && store.ownerRelativePath === '';
-            if (fm['namespace'] !== undefined && !(isRootFile && isRepositoryRootStore)) {
-                const message = isRootFile && isProjectStore && store.ownerRelativePath !== undefined && store.ownerRelativePath !== ''
-                    ? `\`namespace:\` belongs only on the repository-root store's ${INDEX_SEGMENT}.md (${store.namespacePath ?? store.storeRoot}) — a nested store's prefix is derived from its path under ${store.repositoryRoot ?? store.ownerDir ?? store.storeRoot}`
-                    : `\`namespace:\` belongs only on a project store's root ${INDEX_SEGMENT}.md, where it declares the whole store's prefix — drop it here (an explicit \`name:\` is store-LOCAL and never carries a namespace)`;
-                add('error', 'namespace-placement', file, message, named);
-            }
-            if (isRootFile && fm['name'] !== undefined) {
-                add('error', 'root-name', file, `a store's root ${INDEX_SEGMENT}.md carries no \`name:\` — its identity answers at \`${store.namespace}\`; drop the field`, named);
-            }
-        }
-        if (doc === undefined) {
-            // In a project store the missing/invalid declaration is already the finding.
-            if (isRootFile && !isProjectStore) {
-                add('error', 'root-index-unaddressable', file, `a root ${INDEX_SEGMENT}.md has no canonical name in a ${store.scope} store, which declares no namespace — only a project store's root document answers at its namespace, so rename this file to a named document (\`<topic>.md\`) or fold its content into the docs it introduces`);
-            }
-            continue;
-        }
-        if (fm !== null) {
-            if (!isRootFile && fm['name'] !== undefined) {
-                const raw = fm['name'];
-                if (typeof raw !== 'string' || raw.trim() === '') {
-                    add('error', 'local-name', file, `invalid name: ${JSON.stringify(raw)} (expected a non-empty store-local name)`, named);
-                }
-                else {
-                    // Validated as WRITTEN: normalizing first would silently accept an
-                    // `NN-` ordering prefix, which is physical-path-only. The suggestion
-                    // is the normalized spelling.
-                    const valid = validateExplicitLocalName(raw.trim(), store.namespace);
-                    if (!valid.ok) {
-                        const suggested = suggestedLocalName(normalizeDocName(raw.trim()), store.namespace, relPath);
-                        add('error', 'local-name', file, `invalid name \`${raw}\`: ${valid.reason} — ${suggested}`, named);
-                    }
-                }
-            }
-            for (const issue of validateMemoryExtensionValues(fm['extensions'], memoryExtensionValidationCatalog(doc))) {
-                add('error', 'extension', file, `${issue.path}: ${issue.message}`, named);
-            }
-            const lengthError = lintBodyLength(fm, body, doc.name);
-            if (lengthError !== null)
-                add('error', 'length', file, lengthError, named);
-            const shortPreview = lintShortPreviewBody(fm, body);
-            if (shortPreview !== null)
-                add('warning', 'short-preview', file, shortPreview, named);
-            const entries = parsedSubstrateSurfaces(fm);
-            if (options.nestedStore === true && entries.some((e) => e.on === 'boot')) {
-                add('warning', 'nested-store-boot', file, 'nested-store docs never ride the boot catalog, so its boot surfaces entries are inert — drop them', named);
-            }
-            if (isProjectStore && entries.some((e) => e.on === 'workspace-open' && e.at === 'content')) {
-                const complete = entries.some((entry) => {
-                    if (entry.on !== 'read' || entry.at !== 'content')
-                        return false;
-                    return entry.match?.includes('./**') === true;
-                });
-                frontDoors.push({ path: file, root: isRootFile, complete });
-            }
-            for (const entry of entries) {
-                if (entry.on !== 'memory-read')
-                    continue;
-                lintMemoryReadEntry(entry, doc, fm, options.resolvable, mounted, add);
-            }
-        }
-        if (options.resolvable !== undefined && mounted) {
-            for (const name of docLinkNames(body)) {
-                if (options.resolvable.has(name))
-                    continue;
-                add('error', 'dangling-link', file, `dangling doc link [[${name}]]: no memory document or directory in this target view has that exact canonical name.${missingNameDiagnostic(name)}`, named);
-            }
+        if (lintDocumentFile({
+            store,
+            file,
+            relPath,
+            doc: docsByPath.get(file),
+            isProjectStore,
+            mounted,
+            ...(options.resolvable === undefined ? {} : { resolvable: options.resolvable }),
+            nestedStore: options.nestedStore === true,
+            add,
+            frontDoors,
+        }) === 'document') {
+            documents += 1;
         }
     }
     // Same-store canonical collisions. The loader already orders `foo/INDEX.md`
@@ -355,6 +278,143 @@ export function lintMemoryStore(store, options = {}) {
     }
     return makeResult(findings, checked, documents, 1);
 }
+/** Every rule that reads ONE file. The store sweep runs it per file, and
+ *  `lintMemoryDocument` runs it alone; a rule asserted in one caller holds only
+ *  there, so neither reimplements one. Store-level rules (canonical collisions,
+ *  front-door coverage) are the caller's, because one file cannot see them. */
+function lintDocumentFile(ctx) {
+    const { store, file, relPath, doc, isProjectStore, mounted, resolvable, add } = ctx;
+    let fm;
+    let body;
+    try {
+        ({ data: fm, body } = parseFrontmatterGeneric(readText(file)));
+    }
+    catch (e) {
+        add('error', 'yaml', file, `invalid YAML frontmatter: ${(e instanceof Error ? e.message : String(e)).split('\n')[0]}`);
+        return 'yaml-error';
+    }
+    if (NON_DOCUMENT_FILES.has(basename(file)))
+        return 'non-document';
+    const isRootFile = localNameFromPath(relPath) === '';
+    // A file the loader dropped (a root INDEX.md composing to the empty name)
+    // carries no canonical identity, but its frontmatter contract still holds —
+    // the field rules below run before the identity-dependent ones.
+    const named = doc === undefined ? {} : { name: doc.name };
+    const schemaError = lintSubstrateFrontmatter(fm);
+    if (schemaError !== null)
+        add('error', 'schema', file, schemaError, named);
+    if (fm !== null) {
+        const isRepositoryRootStore = isProjectStore && store.ownerRelativePath === '';
+        if (fm['namespace'] !== undefined && !(isRootFile && isRepositoryRootStore)) {
+            const message = isRootFile && isProjectStore && store.ownerRelativePath !== undefined && store.ownerRelativePath !== ''
+                ? `\`namespace:\` belongs only on the repository-root store's ${INDEX_SEGMENT}.md (${store.namespacePath ?? store.storeRoot}) — a nested store's prefix is derived from its path under ${store.repositoryRoot ?? store.ownerDir ?? store.storeRoot}`
+                : `\`namespace:\` belongs only on a project store's root ${INDEX_SEGMENT}.md, where it declares the whole store's prefix — drop it here (an explicit \`name:\` is store-LOCAL and never carries a namespace)`;
+            add('error', 'namespace-placement', file, message, named);
+        }
+        if (isRootFile && fm['name'] !== undefined) {
+            add('error', 'root-name', file, `a store's root ${INDEX_SEGMENT}.md carries no \`name:\` — its identity answers at \`${store.namespace}\`; drop the field`, named);
+        }
+    }
+    if (doc === undefined) {
+        // In a project store the missing/invalid declaration is already the finding.
+        if (isRootFile && !isProjectStore) {
+            add('error', 'root-index-unaddressable', file, `a root ${INDEX_SEGMENT}.md has no canonical name in a ${store.scope} store, which declares no namespace — only a project store's root document answers at its namespace, so rename this file to a named document (\`<topic>.md\`) or fold its content into the docs it introduces`);
+        }
+        return 'document';
+    }
+    if (fm !== null) {
+        if (!isRootFile && fm['name'] !== undefined) {
+            const raw = fm['name'];
+            if (typeof raw !== 'string' || raw.trim() === '') {
+                add('error', 'local-name', file, `invalid name: ${JSON.stringify(raw)} (expected a non-empty store-local name)`, named);
+            }
+            else {
+                // Validated as WRITTEN: normalizing first would silently accept an
+                // `NN-` ordering prefix, which is physical-path-only. The suggestion
+                // is the normalized spelling.
+                const valid = validateExplicitLocalName(raw.trim(), store.namespace);
+                if (!valid.ok) {
+                    const suggested = suggestedLocalName(normalizeDocName(raw.trim()), store.namespace, relPath);
+                    add('error', 'local-name', file, `invalid name \`${raw}\`: ${valid.reason} — ${suggested}`, named);
+                }
+            }
+        }
+        for (const issue of validateMemoryExtensionValues(fm['extensions'], memoryExtensionValidationCatalog(doc))) {
+            add('error', 'extension', file, `${issue.path}: ${issue.message}`, named);
+        }
+        const lengthError = lintBodyLength(fm, body, doc.name);
+        if (lengthError !== null)
+            add('error', 'length', file, lengthError, named);
+        const shortPreview = lintShortPreviewBody(fm, body);
+        if (shortPreview !== null)
+            add('warning', 'short-preview', file, shortPreview, named);
+        const entries = parsedSubstrateSurfaces(fm);
+        if (ctx.nestedStore && entries.some((e) => e.on === 'boot')) {
+            add('warning', 'nested-store-boot', file, 'nested-store docs never ride the boot catalog, so its boot surfaces entries are inert — drop them', named);
+        }
+        if (isProjectStore && entries.some((e) => e.on === 'workspace-open' && e.at === 'content')) {
+            const complete = entries.some((entry) => {
+                if (entry.on !== 'read' || entry.at !== 'content')
+                    return false;
+                return entry.match?.includes('./**') === true;
+            });
+            ctx.frontDoors.push({ path: file, root: isRootFile, complete });
+        }
+        for (const entry of entries) {
+            if (entry.on !== 'memory-read')
+                continue;
+            lintMemoryReadEntry(entry, doc, fm, resolvable, mounted, add);
+        }
+    }
+    if (resolvable !== undefined && mounted) {
+        for (const name of docLinkNames(body)) {
+            if (resolvable.has(name))
+                continue;
+            add('error', 'dangling-link', file, `dangling doc link [[${name}]]: no memory document or directory in this target view has that exact canonical name.${missingNameDiagnostic(name)}`, named);
+        }
+    }
+    return 'document';
+}
+/** Lint ONE document, by absolute path, in the store that holds it. Runs every
+ *  file-level rule the store sweep runs, and the store-level front-door rule
+ *  this one file can violate on its own. It does NOT run the rules that need
+ *  the whole store (canonical collisions, missing front-door coverage), so it
+ *  never replaces `crtr memory lint` — it catches what an author just typed. */
+export function lintMemoryDocument(store, filePath, options = {}) {
+    const findings = [];
+    const base = {
+        scope: store.scope,
+        ...(store.storeRoot === '' ? {} : { storeRoot: store.storeRoot }),
+    };
+    const add = (severity, rule, path, message, extra = {}) => {
+        findings.push({ severity, rule, path, message, ...base, ...extra });
+    };
+    const relPath = relative(store.storeRoot, filePath).split(sep).join('/');
+    const doc = loadStoreMemoryDocs(store, true).find((candidate) => candidate.path === filePath);
+    const frontDoors = [];
+    const outcome = lintDocumentFile({
+        store,
+        file: filePath,
+        relPath,
+        doc,
+        isProjectStore: store.scope === 'project' && store.plugin === undefined,
+        mounted: store.mountStatus === 'ready',
+        ...(options.resolvable === undefined ? {} : { resolvable: options.resolvable }),
+        nestedStore: options.nestedStore === true,
+        add,
+        frontDoors,
+    });
+    // The one store-level rule a single document can break by itself: a front
+    // door anywhere but the store root delivers a second whole doc at every
+    // workspace open. A MISSING front door is the store's fault, not this doc's,
+    // so it stays with the sweep.
+    for (const door of frontDoors) {
+        if (door.root)
+            continue;
+        add('error', 'front-door', door.path, `a project store's workspace front door is its root ${INDEX_SEGMENT}.md, not this doc — a {on: workspace-open, at: content} entry here delivers a second whole document at every workspace open; fold it into the root document or lower this entry`);
+    }
+    return makeResult(findings, 1, outcome === 'document' ? 1 : 0, 1);
+}
 /** The local spelling an invalid explicit `name:` should use: dropping the field
  *  entirely when the physical path already derives the same identity. */
 function suggestedLocalName(local, namespace, physicalRelativePath) {

package/dist/core/profiles/__tests__/fuzzy-match.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/profiles/__tests__/fuzzy-match.test.js

@@ -0,0 +1,51 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { fuzzyMatchProfile } from '../fuzzy-match.js';
+const PROFILES = [
+    { profileId: 'crouter-1a2b3c4d', name: 'crouter' },
+    { profileId: 'northlight-5e6f7a8b', name: 'Northlight' },
+    { profileId: 'personal-ops-9c0d1e2f', name: 'personal ops' },
+];
+function idOf(operand) {
+    return fuzzyMatchProfile(operand, PROFILES).match?.profileId ?? null;
+}
+test('a truncated name resolves to the profile it prefixes', () => {
+    assert.equal(idOf('crout'), 'crouter-1a2b3c4d');
+    assert.equal(idOf('north'), 'northlight-5e6f7a8b');
+});
+test('case and separators are irrelevant', () => {
+    assert.equal(idOf('CROUTER'), 'crouter-1a2b3c4d');
+    assert.equal(idOf('personal-ops'), 'personal-ops-9c0d1e2f');
+    assert.equal(idOf('PersonalOps'), 'personal-ops-9c0d1e2f');
+});
+test('a transposition or a dropped character still resolves', () => {
+    assert.equal(idOf('cruoter'), 'crouter-1a2b3c4d');
+    assert.equal(idOf('crouterr'), 'crouter-1a2b3c4d');
+    assert.equal(idOf('northlite'), 'northlight-5e6f7a8b');
+});
+test('the id slug matches without its generated hex suffix', () => {
+    assert.equal(idOf('personal-ops-9c0d1e2f'), 'personal-ops-9c0d1e2f');
+    assert.equal(idOf('personalops'), 'personal-ops-9c0d1e2f');
+});
+test('a genuinely unrelated operand matches nothing', () => {
+    assert.equal(idOf('zzzzzzzzzz'), null);
+    assert.equal(idOf(''), null);
+});
+test('equally close candidates are reported as a tie, never guessed', () => {
+    const twins = [
+        { profileId: 'alpha-00000001', name: 'alpha' },
+        { profileId: 'alpha-00000002', name: 'alpho' },
+    ];
+    const result = fuzzyMatchProfile('alphx', twins);
+    assert.equal(result.match, null);
+    assert.deepEqual(result.tied.map((c) => c.profileId), ['alpha-00000001', 'alpha-00000002']);
+});
+test('a stronger tier wins over a closer edit distance in a weaker tier', () => {
+    // "nort" is a prefix of northlight and one edit from "note" — the prefix
+    // must win, because a user who stopped typing meant the thing they started.
+    const candidates = [
+        { profileId: 'northlight-5e6f7a8b', name: 'northlight' },
+        { profileId: 'note-11111111', name: 'note' },
+    ];
+    assert.equal(fuzzyMatchProfile('nort', candidates).match?.profileId, 'northlight-5e6f7a8b');
+});

package/dist/core/profiles/fuzzy-match.d.ts

@@ -0,0 +1,19 @@
+/** One candidate offered to the matcher: the durable id plus the mutable name. */
+export interface FuzzyCandidate {
+    readonly profileId: string;
+    readonly name: string;
+}
+export interface FuzzyResult {
+    /** The single profile the needle resolved to, or `null` when nothing was
+     *  close enough or several were equally close. */
+    readonly match: FuzzyCandidate | null;
+    /** Populated only when several profiles tied — the caller reports these so
+     *  the user can disambiguate without running `profile list`. */
+    readonly tied: readonly FuzzyCandidate[];
+}
+/** Resolve a typed operand against the profiles on this host. Returns a single
+ *  match only when it is unambiguously the best one: the strongest tier any
+ *  candidate reached, and within it the single lowest edit distance. A genuine
+ *  tie is reported rather than guessed, because silently running under the
+ *  wrong profile is worse than one more prompt. */
+export declare function fuzzyMatchProfile(operand: string, candidates: readonly FuzzyCandidate[]): FuzzyResult;