projectkeeper 0.0.0-stage → 1.0.0

package/src/ledger/time.ts

@@ -0,0 +1,185 @@
+/**
+ * 发生的时间 (Spec §2.11; CKC-22 AC-10, AC-15): every ledger entry carries when the thing it records happened, with the
+ * basis the program read it from — never a model-written date. The shape is the workbench's own (`model/k-types.ts`
+ * `Occurred`), so an entry can be handed to the views and the evidence resolver as it is.
+ *
+ * Precision is kept as the source gives it: a date-only value stays a date (`2026-09-26`); a clock time is stored as its
+ * instant in UTC (model/time.ts). When the text writes its own date beside the commit time, both are kept (`other`), so
+ * a reader sees where they disagree. When nothing gives a time, the entry is `First observed` at the moment the program
+ * first saw it, marked `undated`.
+ *
+ * Dates written in a text (`Written in text`) are read by one rule, used everywhere a line needs one (`dateContext`):
+ *   1. a date written on the line itself — `2026-09-26`, `2026/9/26`, `2026年9月26日`; `09-26` and `9月26日` only when an
+ *      earlier full date of the same text gives the year (and `09-26` only zero-padded, so `5-6` is never a date);
+ *   2. else the stated date of the entry the line belongs to: the first `日期：…` / `date: …` / `时间：…` line of the entry
+ *      (an entry begins at a Markdown heading or at a line that opens in bold, e.g. `**D83 · …**`);
+ *   3. else a date written on the entry's own first line (`**D77 补（2026-09-26）**`, `### 2026-09-17 round two`);
+ *   4. else the document's stated date: a `date` / `created` / `日期` field in the front matter or in the first 20 lines
+ *      (a "last updated" line is not the date of what the document says, so it never counts);
+ *   5. else none.
+ */
+import type { Occurred, OccurredBasis } from '../model/k-types.ts';
+import { normalizeMaterialTime } from '../model/time.ts';
+
+export type { Occurred, OccurredBasis };
+
+/** The time to store: a date stays a date, a clock time becomes its UTC instant; null when it is not a time. */
+export function materialTime(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  return normalizeMaterialTime(raw);
+}
+
+/** Milliseconds for ordering and range filters; a date-only value orders at its UTC midnight (never displayed). */
+export const msOf = (at: string | null | undefined): number | null => {
+  if (!at) return null;
+  const ms = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(at) ? `${at}T00:00:00Z` : at);
+  return Number.isNaN(ms) ? null : ms;
+};
+
+/** A range bound given by a caller: a date means the start of that day (since) or its end (until), in UTC. */
+export function boundMs(value: string | null | undefined, end: boolean): number | null {
+  const v = (value ?? '').trim();
+  if (!v) return null;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return Date.parse(`${v}T${end ? '23:59:59.999' : '00:00:00.000'}Z`);
+  const ms = Date.parse(v);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/** Date-only prefix, for grouping by day. */
+export const dayOf = (at: string | null | undefined): string | null => (at ? at.slice(0, 10) : null);
+
+/**
+ * A dated occurrence, with the other time the source gives kept beside it (§2.11: a date the text writes is recorded as
+ * well — "正文写明日期的，另记"). Only an other time that is the very same value is left out. An other time on the same
+ * day used to be dropped, which lost a text's own date whenever it named the commit's day, and compared a local date
+ * with the UTC day of an instant, so a commit made just after midnight east of UTC hid a real one-day disagreement
+ * (QC AY, CKC-22 AC-10). Whether the two disagree is for the reader, who sees both.
+ */
+export function occurred(at: string, basis: OccurredBasis, anchor: string | null, other?: { at: string; basis: OccurredBasis; anchor: string | null } | null): Occurred {
+  const keepOther = other && other.at !== at ? other : null;
+  return { at, basis, anchor, ...(keepOther ? { other: keepOther } : {}) };
+}
+
+/** Nothing gives a time: `Undated · first seen <at>`. */
+export function undated(firstSeen: string, anchor: string | null): Occurred {
+  return { at: firstSeen, basis: 'First observed', anchor, undated: true };
+}
+
+// ───────────────────────── dates written in a text ─────────────────────────
+
+const pad = (n: number): string => String(n).padStart(2, '0');
+function realDate(y: number, m: number, d: number): string | null {
+  if (y < 1990 || y > 2100 || m < 1 || m > 12 || d < 1 || d > 31) return null;
+  const check = new Date(Date.UTC(y, m - 1, d));
+  if (check.getUTCMonth() !== m - 1 || check.getUTCDate() !== d) return null;
+  return `${y}-${pad(m)}-${pad(d)}`;
+}
+
+const FULL = /(?<![\d.])((?:19|20)\d{2})[-/.](\d{1,2})[-/.](\d{1,2})(?![\d])/g;
+const CN_FULL = /((?:19|20)\d{2})\s*年\s*(\d{1,2})\s*月\s*(\d{1,2})\s*[日号]/g;
+const SHORT = /(?<![\d:./-])(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])(?![\d:])/g;
+const CN_SHORT = /(?<![\d年])(\d{1,2})\s*月\s*(\d{1,2})\s*[日号]/g;
+
+/** The full dates written on one line, in order; with `year`, also the month-day forms. */
+export function datesOnLine(line: string, year: number | null): { at: string; raw: string; index: number }[] {
+  const out: { at: string; raw: string; index: number }[] = [];
+  for (const m of line.matchAll(FULL)) { const at = realDate(Number(m[1]), Number(m[2]), Number(m[3])); if (at) out.push({ at, raw: m[0], index: m.index! }); }
+  for (const m of line.matchAll(CN_FULL)) { const at = realDate(Number(m[1]), Number(m[2]), Number(m[3])); if (at) out.push({ at, raw: m[0], index: m.index! }); }
+  if (year !== null) {
+    const taken = (i: number) => out.some((o) => i >= o.index && i < o.index + o.raw.length);
+    for (const m of line.matchAll(SHORT)) { if (taken(m.index!)) continue; const at = realDate(year, Number(m[1]), Number(m[2])); if (at) out.push({ at, raw: m[0], index: m.index! }); }
+    for (const m of line.matchAll(CN_SHORT)) { if (taken(m.index!)) continue; const at = realDate(year, Number(m[1]), Number(m[2])); if (at) out.push({ at, raw: m[0], index: m.index! }); }
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+
+/** Every full date written anywhere in a text (for the import-style root rule: does the content predate the commit?). */
+export function fullDatesIn(text: string): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(FULL)) { const at = realDate(Number(m[1]), Number(m[2]), Number(m[3])); if (at) out.push(at); }
+  for (const m of text.matchAll(CN_FULL)) { const at = realDate(Number(m[1]), Number(m[2]), Number(m[3])); if (at) out.push(at); }
+  return out;
+}
+
+/**
+ * A stated date: a `日期：` / `date:` field at the start of a line or after a separator (`编写：…。日期：2026-09-26。`).
+ * "最后更新：…" / "updated: …" never counts: the separator before the word keeps `更新日期` out.
+ */
+const STATED = /(?:^|[\s。；;，,（(|*>])(?:日期|发生时间|时间|date|Date|DATE)\**\s*[:：]/;
+const DOC_STATED = /(?:^|[\s。；;，,（(|*>])(?:日期|创建于|创建|date|Date|DATE|created(?:_at)?|Created)\**\s*[:：]/;
+const ENTRY_START = (l: string): boolean => /^\s{0,3}#{1,6}\s/.test(l) || /^\s{0,3}\*\*\S/.test(l);
+
+export interface WrittenAt {
+  readonly at: string;
+  /** 1-based line the date was read from. */
+  readonly line: number;
+  readonly how: 'line' | 'entry' | 'entry-head' | 'document';
+}
+
+export interface DateContext {
+  /** The written date governing a 1-based line, by the rule above, or null. */
+  at(line: number): WrittenAt | null;
+  /** The document's own stated date (rule 4), or null. */
+  readonly document: WrittenAt | null;
+}
+
+/** Read a text's written dates once; `at(line)` then answers in constant time. */
+export function dateContext(text: string): DateContext {
+  const lines = text.split(/\r?\n/);
+  const n = lines.length;
+  const lineDate: (WrittenAt | null)[] = new Array(n).fill(null);
+  const stated: (string | null)[] = new Array(n).fill(null);
+  let year: number | null = null;
+  let inFence = false;
+  let frontMatter = n > 0 && /^---\s*$/.test(lines[0]!);
+  // The document's own date is stated in its front matter or its preamble (before the first entry below the title).
+  let preamble = true;
+  let document: WrittenAt | null = null;
+  for (let i = 0; i < n; i++) {
+    const l = lines[i]!;
+    if (frontMatter && i > 0 && /^---\s*$/.test(l)) frontMatter = false;
+    if (!frontMatter && ENTRY_START(l) && !/^\s{0,3}#\s/.test(l)) preamble = false;
+    if (/^\s*(```|~~~)/.test(l)) inFence = !inFence;
+    const found = datesOnLine(l, year);
+    if (found[0]) {
+      lineDate[i] = { at: found[0].at, line: i + 1, how: 'line' };
+      const full = found.find((f) => /^\d{4}/.test(f.raw));
+      if (full) year = Number(full.at.slice(0, 4));
+      const s = inFence ? null : STATED.exec(l);
+      if (s) stated[i] = (found.find((f) => f.index >= s.index) ?? found[0]).at;
+      if (!document && ((preamble && i < 20) || (frontMatter && i < 60)) && DOC_STATED.test(l)) {
+        const m = DOC_STATED.exec(l)!;
+        // The date the field names: the first one after the field word.
+        const after = found.find((f) => f.index >= m.index) ?? found[0];
+        document = { at: after.at, line: i + 1, how: 'document' };
+      }
+    }
+  }
+  // Entry blocks: the entry each line belongs to, its stated date and its head's date.
+  const entryOf: number[] = new Array(n).fill(-1);
+  const entryStated = new Map<number, WrittenAt>();
+  let current = -1;
+  inFence = false;
+  for (let i = 0; i < n; i++) {
+    const l = lines[i]!;
+    if (/^\s*(```|~~~)/.test(l)) inFence = !inFence;
+    if (!inFence && ENTRY_START(l)) current = i;
+    entryOf[i] = current;
+    if (current >= 0 && stated[i] && !entryStated.has(current)) entryStated.set(current, { at: stated[i]!, line: i + 1, how: 'entry' });
+  }
+  return {
+    document,
+    at(line: number): WrittenAt | null {
+      const i = Math.min(Math.max(0, Math.floor(line) - 1), n - 1);
+      if (i < 0) return document;
+      if (lineDate[i]) return lineDate[i];
+      const e = entryOf[i]!;
+      if (e >= 0) {
+        const s = entryStated.get(e);
+        if (s) return s;
+        if (lineDate[e]) return { ...lineDate[e]!, how: 'entry-head' };
+      }
+      return document;
+    },
+  };
+}

package/src/ledger/ts-symbols.ts

@@ -0,0 +1,180 @@
+/**
+ * Symbol-level TypeScript queries, on demand (Spec §1.16 row 7, CKC-03 AC-27): who references a
+ * symbol, who implements it, and its call hierarchy, answered by a LanguageService over the current
+ * checkout. Nothing is precomputed into the database; the LanguageService is created lazily per
+ * repository and kept for the process. Every other language is answered by the ledger's code engine in the
+ * same shape (code-engine.ts `engineSymbol`; D98).
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import * as ts from 'typescript';
+import { normalizePath } from '../util/paths.ts';
+
+export interface SymbolLocation {
+  readonly file: string;          // repo-relative, forward slashes
+  readonly line: number;
+  readonly character: number;
+  readonly preview: string;
+}
+
+export interface SymbolResult {
+  readonly symbol: string;
+  readonly file: string;
+  readonly line: number;
+  readonly locations?: readonly SymbolLocation[];
+  readonly incoming?: readonly { readonly from: string; readonly file: string; readonly line: number }[];
+  readonly outgoing?: readonly { readonly to: string; readonly file: string; readonly line: number }[];
+}
+
+export type SymbolQueryKind = 'references' | 'implementations' | 'callers' | 'callees';
+
+interface Host { readonly service: ts.LanguageService; readonly files: readonly string[]; readonly root: string; readonly signature: string }
+const hosts = new Map<string, Host>();
+
+/** One LanguageService per checkout, made again when the set of files changes; a file's version is its modification time. */
+function serviceFor(root: string, relFiles: readonly string[]): Host {
+  const key = normalizePath(root).toLowerCase();
+  const signature = `${relFiles.length}:${relFiles.join('\n').length}`;
+  const existing = hosts.get(key);
+  if (existing && existing.signature === signature) return existing;
+  existing?.service.dispose();
+  const files = relFiles.map((f) => join(root, ...f.split('/')));
+  const host: ts.LanguageServiceHost = {
+    getCompilationSettings: () => ({
+      allowJs: true, checkJs: false, noEmit: true, module: ts.ModuleKind.NodeNext, moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ES2024, strict: false, skipLibCheck: true, allowImportingTsExtensions: true,
+    }),
+    getScriptFileNames: () => [...files],
+    getScriptVersion: (f) => { try { return String(statSync(f).mtimeMs); } catch { return '0'; } },
+    getScriptSnapshot: (f) => {
+      try { return ts.ScriptSnapshot.fromString(readFileSync(f, 'utf8')); } catch { return undefined; }
+    },
+    getCurrentDirectory: () => root,
+    getDirectories: (d) => {
+      try { return ts.sys.getDirectories ? ts.sys.getDirectories(d) : []; } catch { return []; }
+    },
+    getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+    fileExists: (f) => existsSync(f),
+    readFile: (f) => {
+      try { return readFileSync(f, 'utf8'); } catch { return undefined; }
+    },
+    readDirectory: (d, ext, excl, incl, depth) => ts.sys.readDirectory(d, ext, excl, incl, depth),
+    directoryExists: (d) => {
+      try { return ts.sys.directoryExists(d); } catch { return false; }
+    },
+    realpath: (p) => p,
+    useCaseSensitiveFileNames: () => false,
+    getNewLine: () => '\n',
+  };
+  const created: Host = { service: ts.createLanguageService(host), files, root, signature };
+  hosts.set(key, created);
+  return created;
+}
+
+const clip = (s: string, n: number): string => (s.length > n ? `${s.slice(0, n)}…` : s);
+
+/** A file as a repository-relative path with forward slashes (TypeScript and Windows spell the separator differently). */
+const relOf = (root: string, file: string): string => {
+  const f = normalizePath(file).split('\\').join('/');
+  const r = normalizePath(root).split('\\').join('/');
+  return f.toLowerCase().startsWith(`${r.toLowerCase()}/`) ? f.slice(r.length + 1) : f;
+};
+
+/** The program's source file for an absolute path (paths compare case-insensitively here). */
+function sourceFileOf(service: ts.LanguageService, file: string): ts.SourceFile | undefined {
+  const program = service.getProgram();
+  const direct = program?.getSourceFile(file);
+  if (direct) return direct;
+  const wanted = normalizePath(file).toLowerCase();
+  return program?.getSourceFiles().find((f) => normalizePath(f.fileName).toLowerCase() === wanted);
+}
+
+/** First declaration of a name in a file, via the navigation tree. */
+function findByName(service: ts.LanguageService, file: string, name: string): number | null {
+  const tree = service.getNavigationTree(file);
+  const needle = name.trim();
+  let best: number | null = null;
+  const visit = (node: ts.NavigationTree): void => {
+    if (best !== null) return;
+    if (node.text === needle) {
+      // The name itself, not the start of the declaration (its `export` keyword): callers and callees are asked at a
+      // position, and the declaration's start answered nothing (BM found 0 callers of rebuildLedgerInPlace against 12).
+      best = node.nameSpan?.start ?? node.spans[0]?.start ?? null;
+      return;
+    }
+    for (const child of node.childItems ?? []) visit(child);
+  };
+  if (tree) visit(tree);
+  return best;
+}
+
+/**
+ * Answer one symbol query. `file` is repo-relative; the symbol is located by 1-based `line` and
+ * `character`, or by `name` (first declaration in the file). Returns an error string on misuse.
+ */
+export function symbolQuery(
+  root: string, relFiles: readonly string[], kind: SymbolQueryKind,
+  input: { file: string; line?: number; character?: number; name?: string },
+): SymbolResult | string {
+  const rel = input.file.split('\\').join('/').replace(/^\.?\//, '');
+  if (!rel || rel.split('/').some((s) => s === '..')) return `Give a file inside the repository (got “${input.file}”).`;
+  const abs = join(root, ...rel.split('/'));
+  if (!existsSync(abs)) return `${rel} is not in the current checkout of ${root}. Symbol queries read the working tree.`;
+  if (!/\.(tsx?|jsx?|mjs|cts|mts)$/i.test(rel)) return `${rel} is not a TypeScript/JavaScript file; symbol queries cover TS/JS (see ledger coverage for the level of each language).`;
+
+  const { service } = serviceFor(root, relFiles);
+  const sf = sourceFileOf(service, abs);
+  if (!sf) return `${rel} is not among the project's TypeScript files in the ledger.`;
+  let pos: number;
+  if (typeof input.line === 'number' && typeof input.character === 'number') {
+    pos = sf.getPositionOfLineAndCharacter(input.line - 1, input.character - 1);
+  } else if (input.name) {
+    const found = findByName(service, abs, input.name);
+    if (found === null) return `No declaration named “${input.name}” in ${rel}.`;
+    pos = found;
+  } else {
+    return 'Give either line + character (1-based) or a symbol name.';
+  }
+  const lc = ts.getLineAndCharacterOfPosition(sf, pos);
+  const symbolName = input.name ?? service.getQuickInfoAtPosition(abs, pos)?.displayParts?.map((p) => p.text).join('') ?? '';
+  const base: SymbolResult = { symbol: clip(symbolName.trim(), 120), file: rel, line: lc.line + 1 };
+
+  const locOf = (file: string, span: ts.TextSpan): SymbolLocation => {
+    const target = sourceFileOf(service, file);
+    const l = target ? ts.getLineAndCharacterOfPosition(target, span.start) : { line: 0, character: 0 };
+    const lineText = target ? (target.text.split(/\r?\n/)[l.line] ?? '') : '';
+    return { file: relOf(root, file), line: l.line + 1, character: l.character + 1, preview: clip(lineText.trim(), 200) };
+  };
+  const spanStartLine = (file: string, span: ts.TextSpan): number => {
+    const target = sourceFileOf(service, file);
+    return target ? ts.getLineAndCharacterOfPosition(target, span.start).line + 1 : 0;
+  };
+
+  if (kind === 'references') {
+    const refs = service.findReferences(abs, pos) ?? [];
+    const locations: SymbolLocation[] = [];
+    for (const sym of refs) for (const refEntry of sym.references) locations.push(locOf(refEntry.fileName, refEntry.textSpan));
+    return { ...base, locations };
+  }
+  if (kind === 'implementations') {
+    const impls = service.getImplementationAtPosition(abs, pos) ?? [];
+    return { ...base, locations: impls.map((i) => locOf(i.fileName, i.textSpan)) };
+  }
+  if (kind === 'callers') {
+    const incoming = service.provideCallHierarchyIncomingCalls(abs, pos) ?? [];
+    return {
+      ...base,
+      incoming: incoming.map((c) => ({ from: c.from.name, file: relOf(root, c.from.file), line: spanStartLine(c.from.file, c.from.span) })),
+    };
+  }
+  const outgoing = service.provideCallHierarchyOutgoingCalls(abs, pos) ?? [];
+  return {
+    ...base,
+    outgoing: outgoing.map((c) => ({ to: c.to.name, file: relOf(root, c.to.file), line: spanStartLine(c.to.file, c.to.span) })),
+  };
+}
+
+/** The tracked TS/JS files of a repo's current version, for the LanguageService. */
+export function tsFilesOf(relFiles: readonly string[]): string[] {
+  return relFiles.filter((f) => /\.(tsx?|jsx?|mjs|cts|mts)$/i.test(f));
+}