silvermoon 0.0.2 → 0.1.0

package/src/observation.js

@@ -0,0 +1,305 @@
+import { inspectAdoption } from "./adoption.js";
+import {
+  diagnosticInstruction,
+  diagnosticProblem,
+  localize,
+  resolvedConfiguration,
+  summarizeIdeas,
+} from "./dialogue.js";
+import { inspectIdeaLayout } from "./idea-layout.js";
+import { resolveLanguage } from "./language.js";
+import { traceAsync } from "./trace.js";
+import { loadUserConfig } from "./user-config.js";
+
+function projectObservation({
+  configuration,
+  ideas,
+  problems,
+  root,
+  version,
+}) {
+  if (version === undefined) {
+    return {
+      state: "project-setup-required",
+      observedThrough: "root",
+      root,
+      problems,
+    };
+  }
+  if (configuration === undefined) {
+    return {
+      state: "project-setup-required",
+      observedThrough: "version",
+      root,
+      version,
+      problems,
+    };
+  }
+  if (ideas === undefined) {
+    return {
+      state: "project-setup-required",
+      observedThrough: "configuration",
+      root,
+      version,
+      configuration,
+      problems,
+    };
+  }
+  return {
+    state: "project-setup-required",
+    observedThrough: "ideas",
+    root,
+    version,
+    configuration,
+    ideas,
+    problems,
+  };
+}
+
+function localizeFinding(finding, language) {
+  if (finding.sourceDiagnostic) {
+    return {
+      priority: finding.priority,
+      problem: diagnosticProblem(finding.sourceDiagnostic, language),
+      instruction: diagnosticInstruction(finding.sourceDiagnostic, language),
+    };
+  }
+  return {
+    priority: finding.priority,
+    problem: {
+      type: finding.problem.type,
+      summary: localize(
+        language,
+        finding.problem.summary,
+        `Silvermoon 发现 ${finding.problem.type}：${finding.problem.summary}`,
+      ),
+    },
+    instruction: localize(
+      language,
+      finding.instruction,
+      `处理 ${finding.problem.type}：${finding.instruction}`,
+    ),
+  };
+}
+
+export function incompleteObservation({
+  configuration,
+  ideas,
+  problem,
+  root,
+  version,
+}) {
+  return projectObservation({
+    configuration,
+    ideas,
+    problems: [problem],
+    root,
+    version,
+  });
+}
+
+export function unavailableObservation({ root, version, problem }) {
+  return {
+    state: "check-unavailable",
+    root,
+    version,
+    problems: [problem],
+  };
+}
+
+export function repositoryProblemObservation(observation, problems) {
+  return {
+    ...observation,
+    state: "repository-sync-required",
+    problems,
+  };
+}
+
+async function observeSnapshotInternal({
+  allowMissingIdeas = false,
+  contentRoot,
+  gitRoot,
+  ideaLanguage,
+  projectOnly = false,
+  root,
+  snapshotTree,
+  userHome,
+  version,
+}) {
+  const adoption = await traceAsync(
+    "adoption.inspect",
+    {},
+    () => inspectAdoption({ contentRoot, root }),
+  );
+  const user = await traceAsync(
+    "user-config.load",
+    {},
+    () => loadUserConfig({ home: userHome }),
+  );
+  const userFindings = user.diagnostics.map((diagnostic) => ({
+    priority: 30,
+    problem: diagnosticProblem(diagnostic),
+    instruction: diagnostic.remediation,
+    sourceDiagnostic: diagnostic,
+  }));
+  const baseFindings = [...adoption.findings, ...userFindings]
+    .sort((left, right) => left.priority - right.priority);
+  const fallbackLanguage = resolveLanguage({
+    global: user.config?.preferredLanguage,
+  }).tag;
+
+  if (!adoption.gitReady) {
+    const findings = baseFindings.map((finding) =>
+      localizeFinding(finding, fallbackLanguage)
+    );
+    const observation = projectObservation({
+      problems: findings.map(({ problem }) => problem),
+      root: adoption.root,
+    });
+    return {
+      config: null,
+      findings,
+      language: fallbackLanguage,
+      layout: null,
+      observation,
+      projectReady: false,
+    };
+  }
+
+  if (!adoption.config) {
+    const findings = baseFindings.map((finding) =>
+      localizeFinding(finding, fallbackLanguage)
+    );
+    const observation = projectObservation({
+      problems: findings.map(({ problem }) => problem),
+      root: adoption.root,
+      version,
+    });
+    return {
+      config: null,
+      findings,
+      language: fallbackLanguage,
+      layout: null,
+      observation,
+      projectReady: false,
+    };
+  }
+
+  const language = resolveLanguage({
+    idea: ideaLanguage,
+    project: adoption.config.preferredLanguage,
+    global: user.config?.preferredLanguage,
+  }).tag;
+  const configuration = resolvedConfiguration(adoption.config, language);
+  const findings = baseFindings.map((finding) =>
+    localizeFinding(finding, language)
+  );
+  let layout;
+  try {
+    layout = await traceAsync(
+      "idea-layout.inspect",
+      {},
+      () => inspectIdeaLayout({
+        config: adoption.config,
+        gitRoot: gitRoot ?? adoption.root,
+        root: contentRoot ?? adoption.root,
+        snapshotTree,
+      }),
+    );
+  } catch (caught) {
+    layout = {
+      diagnostics: [{
+        code: "layout.inspection-failed",
+        level: "error",
+        message: `Cannot inspect Silvermoon ideas: ${caught.message}`,
+        remediation: "Repair the ideas directory and retry.",
+      }],
+      ideas: [],
+    };
+  }
+  if (allowMissingIdeas) {
+    layout.diagnostics = layout.diagnostics.filter(
+      ({ code }) => code !== "layout.ideas.missing",
+    );
+  }
+
+  const layoutFindings = layout.diagnostics.map((diagnostic) => ({
+    priority: 50,
+    problem: diagnosticProblem(diagnostic, language),
+    instruction: diagnosticInstruction(diagnostic, language),
+  }));
+  findings.push(...layoutFindings);
+  findings.sort((left, right) => left.priority - right.priority);
+
+  if (layout.diagnostics.length > 0) {
+    const observation = projectObservation({
+      configuration,
+      problems: findings.map(({ problem }) => problem),
+      root: adoption.root,
+      version,
+    });
+    return {
+      config: adoption.config,
+      findings,
+      language,
+      layout,
+      observation,
+      projectReady: false,
+    };
+  }
+
+  const ideas = summarizeIdeas(layout.ideas);
+  if (findings.length > 0) {
+    const observation = projectObservation({
+      configuration,
+      ideas,
+      problems: findings.map(({ problem }) => problem),
+      root: adoption.root,
+      version,
+    });
+    return {
+      config: adoption.config,
+      findings,
+      language,
+      layout,
+      observation,
+      projectReady: false,
+    };
+  }
+
+  return {
+    config: adoption.config,
+    findings,
+    language,
+    layout,
+    observation: {
+      state: projectOnly
+        ? "project-ready"
+        : ideas.activeIdeas.length > 0 ? "task-pending" : "idle",
+      root: adoption.root,
+      version,
+      configuration,
+      ideas,
+      problems: [],
+    },
+    projectReady: true,
+  };
+}
+
+export async function observeSnapshot(options) {
+  return traceAsync(
+    "snapshot.observe",
+    {},
+    () => observeSnapshotInternal(options),
+  );
+}
+
+export function withObservationLanguage(observed, ideaLanguage) {
+  if (!observed.config || !ideaLanguage) return observed;
+  const language = resolveLanguage({ idea: ideaLanguage }).tag;
+  const observation = {
+    ...observed.observation,
+    configuration: resolvedConfiguration(observed.config, language),
+  };
+  return { ...observed, language, observation };
+}

package/src/trace.js

@@ -0,0 +1,171 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, lstat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+const TRACE_SCHEMA_VERSION = 1;
+const traceContext = new AsyncLocalStorage();
+
+function durationMilliseconds(started) {
+  return Math.round(Number(process.hrtime.bigint() - started) / 1_000) / 1_000;
+}
+
+function errorName(caught) {
+  return caught instanceof Error ? caught.name : typeof caught;
+}
+
+class Trace {
+  constructor() {
+    this.events = [];
+    this.nextSequence = 1;
+    this.nextSpanId = 1;
+    this.traceId = randomUUID();
+  }
+
+  emit(event) {
+    this.events.push({
+      schemaVersion: TRACE_SCHEMA_VERSION,
+      traceId: this.traceId,
+      sequence: this.nextSequence,
+      timestamp: new Date().toISOString(),
+      ...event,
+    });
+    this.nextSequence += 1;
+  }
+
+  start(name, parentSpanId, attributes) {
+    const span = {
+      attributes,
+      id: String(this.nextSpanId),
+      name,
+      parentSpanId,
+      started: process.hrtime.bigint(),
+    };
+    this.nextSpanId += 1;
+    this.emit({
+      event: "span-start",
+      spanId: span.id,
+      parentSpanId,
+      name,
+      attributes,
+    });
+    return span;
+  }
+
+  end(span, status, attributes = {}) {
+    this.emit({
+      event: "span-end",
+      spanId: span.id,
+      parentSpanId: span.parentSpanId,
+      name: span.name,
+      status,
+      durationMs: durationMilliseconds(span.started),
+      attributes: { ...span.attributes, ...attributes },
+    });
+  }
+
+  serialize() {
+    return `${this.events.map((event) => JSON.stringify(event)).join("\n")}\n`;
+  }
+}
+
+async function requireAvailableTracePath(path) {
+  const parent = dirname(path);
+  const parentMetadata = await lstat(parent);
+  if (!parentMetadata.isDirectory()) {
+    throw new Error(`Trace parent is not a directory: ${parent}`);
+  }
+  await access(parent, constants.W_OK);
+  try {
+    await lstat(path);
+  } catch (caught) {
+    if (caught.code === "ENOENT") return;
+    throw caught;
+  }
+  throw new Error(`Trace file already exists: ${path}`);
+}
+
+export async function traceAsync(name, attributes, callback) {
+  const context = traceContext.getStore();
+  if (!context) return callback();
+
+  const span = context.trace.start(name, context.parentSpanId, attributes);
+  return traceContext.run(
+    { parentSpanId: span.id, trace: context.trace },
+    async () => {
+      try {
+        const result = await callback();
+        context.trace.end(span, "ok");
+        return result;
+      } catch (caught) {
+        context.trace.end(span, "error", { errorName: errorName(caught) });
+        throw caught;
+      }
+    },
+  );
+}
+
+export function traceSync(name, attributes, callback, summarize = () => ({})) {
+  const context = traceContext.getStore();
+  if (!context) return callback();
+
+  const span = context.trace.start(name, context.parentSpanId, attributes);
+  return traceContext.run(
+    { parentSpanId: span.id, trace: context.trace },
+    () => {
+      try {
+        const result = callback();
+        const summary = summarize(result);
+        context.trace.end(
+          span,
+          summary.status ?? "ok",
+          summary.attributes ?? {},
+        );
+        return result;
+      } catch (caught) {
+        context.trace.end(span, "error", { errorName: errorName(caught) });
+        throw caught;
+      }
+    },
+  );
+}
+
+export async function withTraceFile(file, name, attributes, callback) {
+  if (file === undefined) return callback();
+
+  const path = resolve(file);
+  await requireAvailableTracePath(path);
+  const trace = new Trace();
+  let result;
+  let commandError;
+  try {
+    result = await traceContext.run(
+      { parentSpanId: null, trace },
+      () => traceAsync(name, attributes, callback),
+    );
+  } catch (caught) {
+    commandError = caught;
+  }
+
+  let traceError;
+  try {
+    await writeFile(path, trace.serialize(), { encoding: "utf8", flag: "wx" });
+  } catch (caught) {
+    traceError = caught;
+  }
+
+  if (commandError && traceError) {
+    throw new AggregateError(
+      [commandError, traceError],
+      `Command failed and trace file could not be written: ${path}`,
+    );
+  }
+  if (commandError) throw commandError;
+  if (traceError) {
+    throw new Error(`Cannot write trace file ${path}: ${traceError.message}`, {
+      cause: traceError,
+    });
+  }
+  return result;
+}