memorix 1.1.13 → 1.2.1

package/src/knowledge/markdown.ts

@@ -0,0 +1,129 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { atomicWriteFile } from '../store/file-lock.js';
+import type { KnowledgePage, KnowledgePageFrontmatter, KnowledgePageKind, KnowledgePageReviewState, KnowledgePageStatus } from './workspace-types.js';
+
+const PAGE_KINDS: KnowledgePageKind[] = ['topic', 'decision', 'risk', 'index', 'schema', 'log'];
+const PAGE_STATUSES: KnowledgePageStatus[] = ['active', 'proposed'];
+const REVIEW_STATES: KnowledgePageReviewState[] = ['approved', 'needs-review'];
+const LINK_PATTERN = /\[[^\]]+\]\(([^)]+)\)/g;
+
+function hashContent(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function stringField(data: Record<string, unknown>, key: string): string {
+  const value = data[key];
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error('missing required field ' + key);
+  }
+  return value.trim();
+}
+
+function stringArray(data: Record<string, unknown>, key: string): string[] {
+  const value = data[key];
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+    throw new Error('field ' + key + ' must be a string array');
+  }
+  return value.map(item => item.trim()).filter(Boolean);
+}
+
+function optionalString(data: Record<string, unknown>, key: string): string | undefined {
+  const value = data[key];
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string') throw new Error('field ' + key + ' must be text');
+  return value.trim() || undefined;
+}
+
+export function validateKnowledgePageFrontmatter(data: Record<string, unknown>): KnowledgePageFrontmatter {
+  const kind = stringField(data, 'kind') as KnowledgePageKind;
+  const status = stringField(data, 'status') as KnowledgePageStatus;
+  const reviewState = stringField(data, 'reviewState') as KnowledgePageReviewState;
+  if (!PAGE_KINDS.includes(kind)) throw new Error('field kind is invalid');
+  if (!PAGE_STATUSES.includes(status)) throw new Error('field status is invalid');
+  if (!REVIEW_STATES.includes(reviewState)) throw new Error('field reviewState is invalid');
+  return {
+    id: stringField(data, 'id'),
+    title: stringField(data, 'title'),
+    kind,
+    status,
+    reviewState,
+    claimIds: stringArray(data, 'claimIds'),
+    evidenceRefs: stringArray(data, 'evidenceRefs'),
+    ...(optionalString(data, 'snapshotId') ? { snapshotId: optionalString(data, 'snapshotId') } : {}),
+    tags: stringArray(data, 'tags'),
+    sourceHash: stringField(data, 'sourceHash'),
+    generatedAt: stringField(data, 'generatedAt'),
+    updatedAt: stringField(data, 'updatedAt'),
+  };
+}
+
+export function extractInternalMarkdownLinks(body: string): string[] {
+  const links = new Set<string>();
+  for (const match of body.matchAll(LINK_PATTERN)) {
+    const raw = match[1].trim();
+    if (!raw || raw.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(raw)) continue;
+    const pathPart = raw.split('#', 1)[0].replace(/\\/g, '/');
+    if (!pathPart.endsWith('.md')) continue;
+    links.add(pathPart);
+  }
+  return [...links].sort();
+}
+
+export function resolvePageLink(sourceRelativePath: string, target: string): string | undefined {
+  const sourceDir = path.posix.dirname(sourceRelativePath.replace(/\\/g, '/'));
+  const normalized = path.posix.normalize(path.posix.join(sourceDir, target.replace(/\\/g, '/')));
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) return undefined;
+  return normalized;
+}
+
+export function renderKnowledgePage(frontmatter: KnowledgePageFrontmatter, body: string): string {
+  const normalizedBody = body.trimEnd() + '\n';
+  return matter.stringify(normalizedBody, {
+    id: frontmatter.id,
+    title: frontmatter.title,
+    kind: frontmatter.kind,
+    status: frontmatter.status,
+    reviewState: frontmatter.reviewState,
+    claimIds: frontmatter.claimIds,
+    evidenceRefs: frontmatter.evidenceRefs,
+    ...(frontmatter.snapshotId ? { snapshotId: frontmatter.snapshotId } : {}),
+    tags: frontmatter.tags,
+    sourceHash: frontmatter.sourceHash,
+    generatedAt: frontmatter.generatedAt,
+    updatedAt: frontmatter.updatedAt,
+  });
+}
+
+export async function readKnowledgePage(absolutePath: string, workspaceRoot?: string): Promise<KnowledgePage> {
+  const raw = await fs.readFile(absolutePath, 'utf8');
+  try {
+    const parsed = matter(raw);
+    const frontmatter = validateKnowledgePageFrontmatter(parsed.data as Record<string, unknown>);
+    return {
+      absolutePath,
+      relativePath: workspaceRoot
+        ? path.relative(workspaceRoot, absolutePath).split(path.sep).join('/')
+        : path.basename(absolutePath),
+      frontmatter,
+      body: parsed.content.trim(),
+      contentHash: hashContent(raw),
+      links: extractInternalMarkdownLinks(parsed.content),
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : 'invalid page data';
+    throw new Error('Malformed knowledge page frontmatter in ' + absolutePath + ': ' + detail);
+  }
+}
+
+export async function writeKnowledgePage(absolutePath: string, content: string): Promise<string> {
+  await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+  await atomicWriteFile(absolutePath, content);
+  return hashContent(content);
+}
+
+export function pageContentHash(content: string): string {
+  return hashContent(content);
+}

package/src/knowledge/types.ts

@@ -0,0 +1,158 @@
+/**
+ * Durable, source-qualified knowledge contracts.
+ *
+ * Claims are deliberately smaller than a wiki page: they record one assertion,
+ * its lifecycle, and the evidence that makes the assertion safe to retrieve.
+ */
+
+export const KNOWLEDGE_CLAIM_SCOPES = [
+  'project',
+  'workspace',
+  'team',
+  'workflow',
+  'task',
+] as const;
+
+export type KnowledgeClaimScope = typeof KNOWLEDGE_CLAIM_SCOPES[number];
+
+export const KNOWLEDGE_CLAIM_STATUSES = [
+  'active',
+  'superseded',
+  'disputed',
+  'unknown',
+] as const;
+
+export type KnowledgeClaimStatus = typeof KNOWLEDGE_CLAIM_STATUSES[number];
+
+export const KNOWLEDGE_CLAIM_REVIEW_STATES = [
+  'approved',
+  'needs-review',
+  'draft',
+  'rejected',
+] as const;
+
+export type KnowledgeClaimReviewState = typeof KNOWLEDGE_CLAIM_REVIEW_STATES[number];
+
+export const CLAIM_EVIDENCE_KINDS = [
+  'observation',
+  'git',
+  'code',
+  'test',
+  'document',
+  'workflow',
+  'run',
+] as const;
+
+export type ClaimEvidenceKind = typeof CLAIM_EVIDENCE_KINDS[number];
+
+export const CLAIM_EVIDENCE_RELATIONS = [
+  'supports',
+  'contradicts',
+  'derives',
+  'verifies',
+] as const;
+
+export type ClaimEvidenceRelation = typeof CLAIM_EVIDENCE_RELATIONS[number];
+
+export type KnowledgeClaimOrigin = 'explicit' | 'git' | 'derived' | 'model';
+
+export const CLAIM_EVENT_KINDS = [
+  'created',
+  'evidence-added',
+  'reviewed',
+  'conflicted',
+  'superseded',
+  'requalified',
+] as const;
+
+export type ClaimEventKind = typeof CLAIM_EVENT_KINDS[number];
+
+export interface KnowledgeClaim {
+  id: string;
+  projectId: string;
+  subject: string;
+  predicate: string;
+  objectValue: string;
+  scope: KnowledgeClaimScope;
+  /** Exact normalized assertion identity: subject + predicate + object + scope. */
+  claimKey: string;
+  /** Normalized competing-assertion identity: subject + predicate + scope. */
+  conflictKey: string;
+  status: KnowledgeClaimStatus;
+  confidence: number;
+  observedAt: string;
+  validFrom?: string;
+  validTo?: string;
+  supersededBy?: string;
+  reviewState: KnowledgeClaimReviewState;
+  origin: KnowledgeClaimOrigin;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ClaimEvidenceRef {
+  id: string;
+  claimId: string;
+  evidenceKind: ClaimEvidenceKind;
+  evidenceId: string;
+  relation: ClaimEvidenceRelation;
+  snapshotId?: string;
+  locator?: string;
+  capturedHash?: string;
+  createdAt: string;
+}
+
+export interface ClaimEvidenceInput {
+  evidenceKind: ClaimEvidenceKind;
+  evidenceId: string;
+  relation: ClaimEvidenceRelation;
+  snapshotId?: string;
+  locator?: string;
+  capturedHash?: string;
+}
+
+export interface KnowledgeClaimInput {
+  projectId: string;
+  subject: string;
+  predicate: string;
+  objectValue: string;
+  scope: KnowledgeClaimScope;
+  evidence: ClaimEvidenceInput[];
+  confidence?: number;
+  observedAt?: string;
+  validFrom?: string;
+  validTo?: string;
+  status?: KnowledgeClaimStatus;
+  reviewState?: KnowledgeClaimReviewState;
+  origin?: KnowledgeClaimOrigin;
+}
+
+export interface ClaimEvent {
+  id: string;
+  projectId: string;
+  claimId: string;
+  kind: ClaimEventKind;
+  fromStatus?: KnowledgeClaimStatus;
+  toStatus?: KnowledgeClaimStatus;
+  relatedClaimId?: string;
+  detail?: string;
+  createdAt: string;
+}
+
+export interface ClaimConflict {
+  conflictKey: string;
+  claims: KnowledgeClaim[];
+}
+
+export interface ClaimWriteResult {
+  claim: KnowledgeClaim;
+  created: boolean;
+  conflicts: ClaimConflict[];
+}
+
+export interface ClaimSelection {
+  claims: KnowledgeClaim[];
+  cautions: string[];
+  tokenCount: number;
+  reasons: Record<string, string>;
+}