@murphai/murph 0.1.1 → 0.1.13

package/dist/knowledge-cli-contracts.js

@@ -0,0 +1,78 @@
+import { z } from 'incur';
+import { isoTimestampSchema, pathSchema, slugSchema, } from '@murphai/assistant-core/vault-cli-contracts';
+import { DERIVED_KNOWLEDGE_SEARCH_RESULT_FORMAT } from '@murphai/query';
+export const knowledgePageReferenceSchema = z.object({
+    compiledAt: isoTimestampSchema.nullable(),
+    pagePath: pathSchema,
+    pageType: z.string().min(1).nullable(),
+    relatedSlugs: z.array(z.string().min(1)),
+    slug: slugSchema,
+    sourcePaths: z.array(pathSchema),
+    status: z.string().min(1).nullable(),
+    summary: z.string().min(1).nullable(),
+    title: z.string().min(1),
+});
+export const knowledgePageMetadataSchema = knowledgePageReferenceSchema.extend({
+    compiler: z.string().min(1).nullable(),
+    mode: z.string().min(1).nullable(),
+});
+export const knowledgePageSchema = knowledgePageMetadataSchema.extend({
+    body: z.string(),
+    markdown: z.string().min(1),
+});
+export const knowledgeCompileResultSchema = z.object({
+    vault: pathSchema,
+    indexPath: pathSchema,
+    page: knowledgePageMetadataSchema,
+    prompt: z.string().min(1),
+    bodyLength: z.number().int().positive(),
+    savedAt: isoTimestampSchema,
+    warnings: z.array(z.string().min(1)),
+});
+export const knowledgeListResultSchema = z.object({
+    pageCount: z.number().int().nonnegative(),
+    pageType: z.string().min(1).nullable(),
+    pages: z.array(knowledgePageMetadataSchema),
+    status: z.string().min(1).nullable(),
+    vault: pathSchema,
+});
+export const knowledgeSearchHitSchema = knowledgePageReferenceSchema.extend({
+    matchedTerms: z.array(z.string().min(1)),
+    score: z.number(),
+    snippet: z.string().min(1),
+});
+export const knowledgeSearchResultSchema = z.object({
+    format: z.literal(DERIVED_KNOWLEDGE_SEARCH_RESULT_FORMAT),
+    hits: z.array(knowledgeSearchHitSchema),
+    pageType: z.string().min(1).nullable(),
+    query: z.string().min(1),
+    status: z.string().min(1).nullable(),
+    total: z.number().int().nonnegative(),
+    vault: pathSchema,
+});
+export const knowledgeShowResultSchema = z.object({
+    page: knowledgePageSchema,
+    vault: pathSchema,
+});
+export const knowledgeIndexRebuildResultSchema = z.object({
+    indexPath: pathSchema,
+    pageCount: z.number().int().nonnegative(),
+    pageTypes: z.array(z.string().min(1)),
+    rebuilt: z.literal(true),
+    vault: pathSchema,
+});
+export const knowledgeLintProblemSchema = z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+    pagePath: pathSchema,
+    slug: slugSchema.nullable(),
+    severity: z.enum(['error', 'warning']),
+});
+export const knowledgeLintResultSchema = z.object({
+    ok: z.boolean(),
+    pageCount: z.number().int().nonnegative(),
+    problemCount: z.number().int().nonnegative(),
+    problems: z.array(knowledgeLintProblemSchema),
+    vault: pathSchema,
+});
+//# sourceMappingURL=knowledge-cli-contracts.js.map

package/dist/knowledge-cli-contracts.js.map

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

package/dist/knowledge-documents.d.ts

@@ -0,0 +1,44 @@
+import { type DerivedKnowledgeNode } from '@murphai/query';
+import { type KnowledgePage, type KnowledgePageMetadata } from './knowledge-cli-contracts.js';
+export interface KnowledgeSourceEntry {
+    content: string;
+    relativePath: string;
+}
+export declare function deriveKnowledgeTitle(input: {
+    existingPage?: DerivedKnowledgeNode | null;
+    prompt: string;
+    slug?: string | null;
+    title?: string | null;
+}): string;
+export declare function buildKnowledgeCompilePrompt(input: {
+    existingPage: DerivedKnowledgeNode | null;
+    pageType: string;
+    prompt: string;
+    slug: string;
+    sourceEntries: readonly KnowledgeSourceEntry[];
+    status: string;
+    title: string;
+}): string;
+export declare function normalizeKnowledgeBody(response: string, title: string): string;
+export declare function buildKnowledgeMarkdown(input: {
+    body: string;
+    compiledAt: string;
+    compiler: string;
+    mode?: string | null;
+    pageType: string;
+    slug: string;
+    sourcePaths: string[];
+    status: string;
+    summary: string | null;
+    title: string;
+}): string;
+export declare function buildKnowledgePageRelativePath(slug: string): string;
+export declare function toKnowledgeMetadata(page: DerivedKnowledgeNode): KnowledgePageMetadata;
+export declare function toKnowledgePage(page: DerivedKnowledgeNode, markdown: string): KnowledgePage;
+export declare function normalizeSourcePathInputs(value: readonly string[] | null | undefined): string[];
+export declare function matchesKnowledgeFilter(value: string | null | undefined, filter: string | null): boolean;
+export declare function truncateContextText(value: string, limit: number): {
+    text: string;
+    truncated: boolean;
+};
+//# sourceMappingURL=knowledge-documents.d.ts.map

package/dist/knowledge-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-documents.d.ts","sourceRoot":"","sources":["../src/knowledge-documents.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAA;AAKrC,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,YAAY,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAA;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,GAAG,MAAM,CAmBT;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAA;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd,GAAG,MAAM,CAuDT;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgB9E;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;CACd,GAAG,MAAM,CAgBT;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,CAcrF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAM3F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAU/F;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAMT;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAatC"}

package/dist/knowledge-documents.js

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { normalizeNullableString as normalizeOptionalText } from '@murphai/assistant-core/text/shared';
+import { stringifyFrontmatterDocument } from '@murphai/core';
+import { DERIVED_KNOWLEDGE_PAGES_ROOT, humanizeKnowledgeTag, normalizeKnowledgeTag, orderedUniqueStrings, } from '@murphai/query';
+import {} from './knowledge-cli-contracts.js';
+const MAX_EXISTING_PAGE_CHARS = 18_000;
+const LOCAL_CONTEXT_TRUNCATION_SUFFIX = '\n\n[truncated locally]';
+export function deriveKnowledgeTitle(input) {
+    const explicitTitle = normalizeOptionalText(input.title);
+    if (explicitTitle) {
+        return explicitTitle;
+    }
+    if (input.existingPage?.title) {
+        return input.existingPage.title;
+    }
+    const normalizedPrompt = input.prompt.replace(/\s+/gu, ' ').trim();
+    if (normalizedPrompt.length > 0) {
+        return normalizedPrompt.length <= 80
+            ? normalizedPrompt
+            : `${normalizedPrompt.slice(0, 77).trimEnd()}...`;
+    }
+    const slug = normalizeOptionalText(input.slug);
+    return slug ? humanizeKnowledgeTag(slug) : 'Derived knowledge page';
+}
+export function buildKnowledgeCompilePrompt(input) {
+    const sections = [
+        'You are compiling one page in Murph\'s local-first derived knowledge wiki.',
+        'Return markdown only. Do not include YAML frontmatter and do not wrap the answer in code fences.',
+        'Write a calm, inspectable dossier rather than coaching copy. Prefer source-backed synthesis, note uncertainty and contradictions, and avoid purity language, nagging, or protocol accumulation.',
+        'Use clear markdown sections. Start with one H1 heading for the page title. Use `[[slug]]` wikilinks in a `## Related` section when another knowledge page would genuinely help. Do not include a `## Sources` section because the CLI appends that automatically.',
+        [
+            'Requested page metadata:',
+            `- title: ${input.title}`,
+            `- slug: ${input.slug}`,
+            `- page type: ${input.pageType}`,
+            `- status: ${input.status}`,
+        ].join('\n'),
+        ['User instruction:', input.prompt.trim()].join('\n\n'),
+    ];
+    if (input.existingPage) {
+        const existingBody = stripGeneratedKnowledgeSection(input.existingPage.body, [
+            'Sources',
+            'Source notes',
+            'Source files',
+        ]);
+        sections.push([
+            'Existing saved page (update it instead of starting from scratch when useful):',
+            `- path: ${input.existingPage.relativePath}`,
+            `- title: ${input.existingPage.title}`,
+            `- page type: ${input.existingPage.pageType ?? 'unknown'}`,
+            `- status: ${input.existingPage.status ?? 'unknown'}`,
+            '',
+            truncateContextText(existingBody, MAX_EXISTING_PAGE_CHARS).text,
+        ].join('\n'));
+    }
+    if (input.sourceEntries.length === 0) {
+        sections.push('No local source files were supplied for this compile. Rely on the user instruction and any existing page context only.');
+    }
+    else {
+        sections.push([
+            'Local source files:',
+            ...input.sourceEntries.flatMap((entry) => [
+                `### ${entry.relativePath}`,
+                '```text',
+                entry.content,
+                '```',
+            ]),
+        ].join('\n\n'));
+    }
+    return sections.join('\n\n');
+}
+export function normalizeKnowledgeBody(response, title) {
+    let body = response.replace(/\r\n?/gu, '\n').trim();
+    if (/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/u.test(body)) {
+        body = body.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/u, '').trim();
+    }
+    body = stripGeneratedKnowledgeSection(body, ['Sources', 'Source notes', 'Source files']);
+    if (/^#\s+/u.test(body)) {
+        body = body.replace(/^#\s+[^\n]*$/mu, `# ${title}`);
+    }
+    else {
+        body = `# ${title}\n\n${body}`;
+    }
+    return body.trim();
+}
+export function buildKnowledgeMarkdown(input) {
+    const attributes = compactRecord({
+        compiledAt: input.compiledAt,
+        compiler: input.compiler,
+        mode: input.mode,
+        pageType: input.pageType,
+        slug: input.slug,
+        status: input.status,
+        summary: input.summary,
+        title: input.title,
+    });
+    return stringifyFrontmatterDocument({
+        attributes,
+        body: appendKnowledgeSourcesSection(input.body, input.sourcePaths),
+    });
+}
+export function buildKnowledgePageRelativePath(slug) {
+    return path.posix.join(DERIVED_KNOWLEDGE_PAGES_ROOT, `${slug}.md`);
+}
+export function toKnowledgeMetadata(page) {
+    return {
+        compiler: page.compiler,
+        compiledAt: page.compiledAt,
+        mode: normalizeKnowledgeMode(page.mode),
+        pagePath: page.relativePath,
+        pageType: page.pageType,
+        relatedSlugs: page.relatedSlugs,
+        slug: page.slug,
+        sourcePaths: page.sourcePaths,
+        status: page.status,
+        summary: page.summary,
+        title: page.title,
+    };
+}
+export function toKnowledgePage(page, markdown) {
+    return {
+        ...toKnowledgeMetadata(page),
+        body: page.body,
+        markdown,
+    };
+}
+export function normalizeSourcePathInputs(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return orderedUniqueStrings(value
+        .map((entry) => String(entry ?? '').trim())
+        .filter((entry) => entry.length > 0));
+}
+export function matchesKnowledgeFilter(value, filter) {
+    if (!filter) {
+        return true;
+    }
+    return normalizeKnowledgeTag(value) === filter;
+}
+export function truncateContextText(value, limit) {
+    if (value.length <= limit) {
+        return {
+            text: value,
+            truncated: false,
+        };
+    }
+    const textLimit = Math.max(0, limit - LOCAL_CONTEXT_TRUNCATION_SUFFIX.length);
+    return {
+        text: `${value.slice(0, textLimit).trimEnd()}${LOCAL_CONTEXT_TRUNCATION_SUFFIX}`,
+        truncated: true,
+    };
+}
+function normalizeKnowledgeMode(value) {
+    const normalized = normalizeOptionalText(value);
+    return normalized ?? null;
+}
+function appendKnowledgeSourcesSection(body, sourcePaths) {
+    if (sourcePaths.length === 0) {
+        return `${body.trim()}\n`;
+    }
+    return [
+        body.trim(),
+        '',
+        '## Sources',
+        '',
+        ...sourcePaths.map((sourcePath) => `- \`${sourcePath}\``),
+        '',
+    ].join('\n');
+}
+function stripGeneratedKnowledgeSection(body, headings) {
+    let normalized = body;
+    for (const heading of headings) {
+        const pattern = new RegExp(`(^|\\n)##\\s+${escapeRegExp(heading)}\\s*\\n[\\s\\S]*?(?=\\n##\\s+|$)`, 'giu');
+        normalized = normalized.replace(pattern, '$1').trim();
+    }
+    return normalized;
+}
+function compactRecord(value) {
+    const compacted = {};
+    for (const [key, current] of Object.entries(value)) {
+        if (current === null || current === undefined) {
+            continue;
+        }
+        if (Array.isArray(current) && current.length === 0) {
+            continue;
+        }
+        compacted[key] = current;
+    }
+    return compacted;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+//# sourceMappingURL=knowledge-documents.js.map

package/dist/knowledge-documents.js.map

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

package/dist/knowledge-lint.d.ts

@@ -0,0 +1,11 @@
+import { type DerivedKnowledgeGraph, type DerivedKnowledgeGraphIssue, type DerivedKnowledgeNode } from '@murphai/query';
+import { type KnowledgeLintProblem } from './knowledge-cli-contracts.js';
+export declare function collectKnowledgeLintProblems(input: {
+    graph: DerivedKnowledgeGraph;
+    issues: readonly DerivedKnowledgeGraphIssue[];
+    pathExists: (candidatePath: string) => Promise<boolean>;
+}): Promise<KnowledgeLintProblem[]>;
+export declare function requireUniqueKnowledgePageBySlug(graph: DerivedKnowledgeGraph, slug: string, action: 'compile' | 'reload' | 'show'): DerivedKnowledgeNode | null;
+export declare function assertKnowledgeSourcePathAllowed(sourcePath: string): void;
+export declare function sortKnowledgeProblems(problems: readonly KnowledgeLintProblem[]): KnowledgeLintProblem[];
+//# sourceMappingURL=knowledge-lint.d.ts.map

package/dist/knowledge-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-lint.d.ts","sourceRoot":"","sources":["../src/knowledge-lint.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AAQxE,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACxD,KAAK,EAAE,qBAAqB,CAAA;IAC5B,MAAM,EAAE,SAAS,0BAA0B,EAAE,CAAA;IAC7C,UAAU,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACxD,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAsClC;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,GACpC,oBAAoB,GAAG,IAAI,CAc7B;AAED,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAmBzE;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GACxC,oBAAoB,EAAE,CAgBxB"}

package/dist/knowledge-lint.js

@@ -0,0 +1,254 @@
+import path from 'node:path';
+import { VaultCliError } from '@murphai/assistant-core/vault-cli-errors';
+import { extractKnowledgeRelatedSlugs, extractKnowledgeSourcePaths, sameKnowledgeStringSet, } from '@murphai/query';
+import {} from './knowledge-cli-contracts.js';
+const FORBIDDEN_KNOWLEDGE_SOURCE_ROOTS = ['derived', '.runtime', 'assistant-state'];
+const KNOWLEDGE_PROBLEM_SEVERITY_ORDER = {
+    error: 0,
+    warning: 1,
+};
+export async function collectKnowledgeLintProblems(input) {
+    const problems = input.issues.map((issue) => ({
+        code: `parse_${issue.parser}`,
+        message: issue.lineNumber !== undefined
+            ? `${issue.reason} (line ${issue.lineNumber}).`
+            : issue.reason,
+        pagePath: issue.relativePath,
+        slug: null,
+        severity: 'error',
+    }));
+    const slugCounts = new Map();
+    for (const page of input.graph.nodes) {
+        const duplicatePaths = slugCounts.get(page.slug) ?? [];
+        duplicatePaths.push(page.relativePath);
+        slugCounts.set(page.slug, duplicatePaths);
+        problems.push(...(await collectKnowledgePageProblems(page, input.graph, input.pathExists)));
+    }
+    for (const [slug, pagePaths] of slugCounts) {
+        if (pagePaths.length <= 1) {
+            continue;
+        }
+        for (const pagePath of pagePaths) {
+            problems.push({
+                code: 'duplicate_slug',
+                message: `Derived knowledge slug "${slug}" appears in multiple files.`,
+                pagePath,
+                slug,
+                severity: 'error',
+            });
+        }
+    }
+    return sortKnowledgeProblems(problems);
+}
+export function requireUniqueKnowledgePageBySlug(graph, slug, action) {
+    const matchingPages = graph.nodes.filter((node) => node.slug === slug);
+    if (matchingPages.length <= 1) {
+        return matchingPages[0] ?? null;
+    }
+    throw new VaultCliError('knowledge_duplicate_slug', `Knowledge slug "${slug}" appears in multiple files and cannot be ${describeKnowledgeDuplicateSlugAction(action)} safely until the duplicate is resolved.`, {
+        pagePaths: matchingPages.map((node) => node.relativePath),
+        slug,
+    });
+}
+export function assertKnowledgeSourcePathAllowed(sourcePath) {
+    const normalizedPath = normalizeKnowledgeSourcePolicyPath(sourcePath);
+    if (!normalizedPath) {
+        throw new VaultCliError('knowledge_invalid_source_path', `Knowledge source path "${sourcePath}" must be a vault-relative file path.`, { sourcePath });
+    }
+    if (isKnowledgeSourcePathAllowed(normalizedPath)) {
+        return;
+    }
+    throw new VaultCliError('knowledge_forbidden_source_path', `Knowledge source path "${sourcePath}" points into derived or runtime state and must not be used for knowledge compilation.`, { sourcePath: normalizedPath });
+}
+export function sortKnowledgeProblems(problems) {
+    return [...problems].sort((left, right) => {
+        const severityComparison = KNOWLEDGE_PROBLEM_SEVERITY_ORDER[left.severity] -
+            KNOWLEDGE_PROBLEM_SEVERITY_ORDER[right.severity];
+        if (severityComparison !== 0) {
+            return severityComparison;
+        }
+        const pathComparison = left.pagePath.localeCompare(right.pagePath);
+        if (pathComparison !== 0) {
+            return pathComparison;
+        }
+        return left.code.localeCompare(right.code);
+    });
+}
+async function collectKnowledgePageProblems(page, graph, pathExists) {
+    const problems = [];
+    const pagePath = page.relativePath;
+    const fileSlug = path.posix.basename(page.relativePath, '.md');
+    if (page.body.trim().length === 0) {
+        problems.push({
+            code: 'empty_body',
+            message: 'Knowledge page body is empty.',
+            pagePath,
+            slug: page.slug,
+            severity: 'error',
+        });
+    }
+    if (!page.pageType) {
+        problems.push({
+            code: 'missing_page_type',
+            message: 'Knowledge page frontmatter should include `pageType`.',
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    if (!page.status) {
+        problems.push({
+            code: 'missing_status',
+            message: 'Knowledge page frontmatter should include `status`.',
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    if (!page.summary) {
+        problems.push({
+            code: 'missing_summary',
+            message: 'Knowledge page frontmatter should include `summary` or enough body text to derive one.',
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    if (page.slug !== fileSlug) {
+        problems.push({
+            code: 'slug_path_mismatch',
+            message: `Knowledge page slug "${page.slug}" should match file name "${fileSlug}".`,
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    if (page.sourcePaths.length === 0) {
+        problems.push({
+            code: 'missing_sources',
+            message: 'Knowledge page does not list any source paths.',
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    const frontmatterSourcePaths = readKnowledgeStringArrayAttribute(page.attributes, 'sourcePaths');
+    const frontmatterRelatedSlugs = readKnowledgeStringArrayAttribute(page.attributes, 'relatedSlugs');
+    const normalizedFrontmatterSourcePaths = collectNormalizedSourcePaths(frontmatterSourcePaths, pagePath, page.slug, problems);
+    const normalizedBodySourcePaths = collectNormalizedSourcePaths(extractKnowledgeSourcePaths(page.body), pagePath, page.slug, problems);
+    if ((normalizedFrontmatterSourcePaths.length > 0 || normalizedBodySourcePaths.length > 0) &&
+        !sameKnowledgeStringSet(normalizedFrontmatterSourcePaths, normalizedBodySourcePaths)) {
+        problems.push({
+            code: 'source_paths_drift',
+            message: 'Knowledge page frontmatter `sourcePaths` does not match the canonical `## Sources` section.',
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    const bodyRelatedSlugs = extractKnowledgeRelatedSlugs(page.body, page.slug);
+    if ((frontmatterRelatedSlugs.length > 0 || bodyRelatedSlugs.length > 0) &&
+        !sameKnowledgeStringSet(frontmatterRelatedSlugs, bodyRelatedSlugs)) {
+        problems.push({
+            code: 'related_slugs_drift',
+            message: 'Knowledge page frontmatter `relatedSlugs` does not match the canonical body wikilinks.',
+            pagePath,
+            slug: page.slug,
+            severity: 'warning',
+        });
+    }
+    for (const relatedSlug of page.relatedSlugs) {
+        if (!graph.bySlug.has(relatedSlug)) {
+            problems.push({
+                code: 'missing_related_page',
+                message: `Related slug "${relatedSlug}" does not exist in derived knowledge pages.`,
+                pagePath,
+                slug: page.slug,
+                severity: 'warning',
+            });
+        }
+    }
+    for (const sourcePath of normalizedBodySourcePaths) {
+        const sourceExists = await pathExists(sourcePath);
+        if (!sourceExists) {
+            problems.push({
+                code: 'missing_source_path',
+                message: `Source path "${sourcePath}" does not exist inside the vault.`,
+                pagePath,
+                slug: page.slug,
+                severity: 'error',
+            });
+        }
+    }
+    return problems;
+}
+function readKnowledgeStringArrayAttribute(attributes, key) {
+    const value = attributes[key];
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .flatMap((entry) => (typeof entry === 'string' ? [entry.trim()] : []))
+        .filter((entry) => entry.length > 0);
+}
+function collectNormalizedSourcePaths(sourcePaths, pagePath, slug, problems) {
+    const normalizedSourcePaths = [];
+    for (const rawSourcePath of sourcePaths) {
+        const normalizedSourcePath = normalizeKnowledgeSourcePolicyPath(rawSourcePath);
+        if (!normalizedSourcePath) {
+            problems.push({
+                code: 'invalid_source_path',
+                message: `Source path "${rawSourcePath}" is not a valid vault-relative file path.`,
+                pagePath,
+                slug,
+                severity: 'error',
+            });
+            continue;
+        }
+        if (!isKnowledgeSourcePathAllowed(normalizedSourcePath)) {
+            problems.push({
+                code: 'forbidden_source_path',
+                message: `Source path "${rawSourcePath}" points into derived or runtime state and must not be used for knowledge compilation.`,
+                pagePath,
+                slug,
+                severity: 'error',
+            });
+            continue;
+        }
+        normalizedSourcePaths.push(normalizedSourcePath);
+    }
+    return normalizedSourcePaths;
+}
+function normalizeKnowledgeSourcePolicyPath(value) {
+    const trimmed = String(value ?? '').trim().replace(/\\/gu, '/');
+    if (!trimmed || trimmed.startsWith('/')) {
+        return null;
+    }
+    if (/^[A-Za-z]:\//u.test(trimmed)) {
+        return null;
+    }
+    const normalized = path.posix.normalize(trimmed).replace(/^\.\/+/u, '');
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) {
+        return null;
+    }
+    return normalized;
+}
+function isKnowledgeSourcePathAllowed(relativePath) {
+    const firstSegment = relativePath.split('/')[0] ?? '';
+    return !FORBIDDEN_KNOWLEDGE_SOURCE_ROOTS.includes(firstSegment);
+}
+function describeKnowledgeDuplicateSlugAction(action) {
+    switch (action) {
+        case 'compile':
+            return 'compiled';
+        case 'reload':
+            return 'reloaded';
+        case 'show':
+            return 'shown';
+    }
+}
+//# sourceMappingURL=knowledge-lint.js.map

package/dist/knowledge-lint.js.map

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