silvermoon 0.2.1 → 0.3.0-rc.1

package/src/guidance.js

@@ -1,10 +1,8 @@
 import { TextDecoder } from "node:util";
 
 import {
-  gitObjectSize,
-  inspectTreeEntry,
-  listTreeEntries,
-  readGitBlob,
+  inspectTree,
+  readGitBlobs,
 } from "./git.js";
 import {
   GUIDANCE_PHASES,
@@ -50,22 +48,20 @@ function unexpectedEntry(name) {
   );
 }
 
-function inspectContent(gitRoot, entry, phase) {
+function contentSizeDiagnostic(entry, phase) {
   const path = phaseGuidancePath(phase);
-  const size = gitObjectSize(gitRoot, entry.object);
-  if (size > MAX_PHASE_GUIDANCE_BYTES) {
-    return {
-      diagnostic: error(
-        "guidance.file.too-large",
-        path,
-        `Phase guidance exceeds the ${MAX_PHASE_GUIDANCE_BYTES}-byte limit: ${path}`,
-        `Reduce ${path} to at most ${MAX_PHASE_GUIDANCE_BYTES} UTF-8 bytes.`,
-      ),
-    };
-  }
+  if (entry.size <= MAX_PHASE_GUIDANCE_BYTES) return null;
+  return error(
+    "guidance.file.too-large",
+    path,
+    `Phase guidance exceeds the ${MAX_PHASE_GUIDANCE_BYTES}-byte limit: ${path}`,
+    `Reduce ${path} to at most ${MAX_PHASE_GUIDANCE_BYTES} UTF-8 bytes.`,
+  );
+}
 
-  const bytes = readGitBlob(gitRoot, entry.object);
-  if (bytes.length !== size) {
+function inspectContent(bytes, entry, phase) {
+  const path = phaseGuidancePath(phase);
+  if (bytes.length !== entry.size) {
     throw new Error(
       `Git blob ${entry.object} changed size while reading ${path}`,
     );
@@ -121,11 +117,20 @@ function inspectContent(gitRoot, entry, phase) {
 }
 
 async function inspectGuidanceInternal({
+  filesystem,
   gitRoot,
   phase,
   snapshotTree,
 }) {
-  const rootEntry = inspectTreeEntry(gitRoot, snapshotTree, GUIDANCE_ROOT);
+  const treeEntries = filesystem === undefined
+    ? inspectTree(gitRoot, snapshotTree, GUIDANCE_ROOT)
+    : null;
+  const rootEntry = treeEntries === null
+    ? filesystem.snapshotEntry(GUIDANCE_ROOT)
+    : treeEntries.find(({ name }) => name === GUIDANCE_ROOT);
+  if (rootEntry === undefined) {
+    return { state: "absent", diagnostics: [] };
+  }
   if (rootEntry === null) {
     return { state: "absent", diagnostics: [] };
   }
@@ -133,7 +138,15 @@ async function inspectGuidanceInternal({
     return { state: "invalid", diagnostics: [invalidDirectory()] };
   }
 
-  const entries = listTreeEntries(gitRoot, rootEntry.object, GUIDANCE_ROOT);
+  const prefix = `${GUIDANCE_ROOT}/`;
+  const entries = (
+    treeEntries === null
+      ? filesystem.snapshotEntries(GUIDANCE_ROOT)
+      : treeEntries.filter(({ name }) =>
+        name.startsWith(prefix) && !name.slice(prefix.length).includes("/")
+      )
+  )
+    .map((entry) => ({ ...entry, name: entry.name.slice(prefix.length) }));
   const entriesByName = new Map(entries.map((entry) => [entry.name, entry]));
   const phases = phase === undefined ? GUIDANCE_PHASES : [phase];
   const diagnostics = [];
@@ -153,6 +166,7 @@ async function inspectGuidanceInternal({
 
   let selectedGuidance;
   let selectedPresent = false;
+  const contentEntries = [];
   for (const candidate of phases) {
     const path = phaseGuidancePath(candidate);
     const name = path.slice(`${GUIDANCE_ROOT}/`.length);
@@ -163,8 +177,29 @@ async function inspectGuidanceInternal({
       diagnostics.push(invalidFile(path));
       continue;
     }
-    const inspected = inspectContent(gitRoot, entry, candidate);
-    if (inspected.diagnostic) diagnostics.push(inspected.diagnostic);
+    const sizeDiagnostic = contentSizeDiagnostic(entry, candidate);
+    if (sizeDiagnostic) {
+      diagnostics.push(sizeDiagnostic);
+      continue;
+    }
+    contentEntries.push({ candidate, entry });
+  }
+
+  const blobs = filesystem === undefined
+    ? readGitBlobs(
+        gitRoot,
+        contentEntries.map(({ entry }) => entry.object),
+      )
+    : new Map(await Promise.all(contentEntries.map(async ({ candidate, entry }) => [
+        entry.object,
+        await filesystem.snapshotFile(phaseGuidancePath(candidate)),
+      ])));
+  for (const { candidate, entry } of contentEntries) {
+    const bytes = blobs.get(entry.object);
+    if (bytes === undefined) {
+      throw new Error(`Missing Git blob content for ${entry.object}`);
+    }
+    const inspected = inspectContent(bytes, entry, candidate);
     if (inspected.diagnostics) diagnostics.push(...inspected.diagnostics);
     if (phase !== undefined && inspected.guidance) {
       selectedGuidance = inspected.guidance;
@@ -183,6 +218,7 @@ async function inspectGuidanceInternal({
 }
 
 export async function inspectPhaseGuidance({
+  filesystem,
   gitRoot,
   phase,
   snapshotTree,
@@ -194,6 +230,7 @@ export async function inspectPhaseGuidance({
     async () => {
       try {
         return await inspectGuidanceInternal({
+          filesystem,
           gitRoot,
           phase,
           snapshotTree,
@@ -214,6 +251,7 @@ export async function inspectPhaseGuidance({
 }
 
 export async function inspectAllGuidance({
+  filesystem,
   gitRoot,
   snapshotTree,
 }) {
@@ -222,7 +260,11 @@ export async function inspectAllGuidance({
     { scope: "all" },
     async () => {
       try {
-        return await inspectGuidanceInternal({ gitRoot, snapshotTree });
+        return await inspectGuidanceInternal({
+          filesystem,
+          gitRoot,
+          snapshotTree,
+        });
       } catch (caught) {
         return {
           state: "invalid",

package/src/idea-layout.js

@@ -5,6 +5,8 @@ import { deriveIdeaState, isValidUlid, parseIdeaStatus } from "./ideas.js";
 import { inspectTreePaths, worktreeSnapshot } from "./git.js";
 import { IDEAS_ROOT, ideaPaths } from "./layout.js";
 
+const DEFAULT_FILESYSTEM = { lstat, readFile, readdir };
+
 function displayPath(root, path) {
   return relative(root, path).replaceAll("\\", "/");
 }
@@ -13,18 +15,18 @@ function error(code, path, message, remediation) {
   return { code, level: "error", path, message, remediation };
 }
 
-async function metadata(path) {
+async function metadata(path, filesystem) {
   try {
-    return await lstat(path);
+    return await filesystem.lstat(path);
   } catch (caught) {
     if (caught.code === "ENOENT") return null;
     throw caught;
   }
 }
 
-async function requireDirectory(root, path, diagnostics) {
+async function requireDirectory(root, path, diagnostics, filesystem) {
   const absolute = resolve(root, path);
-  const value = await metadata(absolute);
+  const value = await metadata(absolute, filesystem);
   if (!value || !value.isDirectory() || value.isSymbolicLink()) {
     diagnostics.push(error(
       "idea.world.invalid-directory",
@@ -37,9 +39,9 @@ async function requireDirectory(root, path, diagnostics) {
   return true;
 }
 
-async function requireDocument(root, path, diagnostics) {
+async function requireDocument(root, path, diagnostics, filesystem) {
   const absolute = resolve(root, path);
-  const value = await metadata(absolute);
+  const value = await metadata(absolute, filesystem);
   if (!value || !value.isFile() || value.isSymbolicLink()) {
     diagnostics.push(error(
       "idea.world.missing-document",
@@ -52,8 +54,8 @@ async function requireDocument(root, path, diagnostics) {
   return true;
 }
 
-async function requireLedger(root, path, diagnostics) {
-  const value = await metadata(resolve(root, path));
+async function requireLedger(root, path, diagnostics, filesystem) {
+  const value = await metadata(resolve(root, path), filesystem);
   if (!value) {
     diagnostics.push(error(
       "idea.ledger.missing-file",
@@ -75,11 +77,13 @@ async function requireLedger(root, path, diagnostics) {
   return true;
 }
 
-async function rejectSymlinks(root, path, diagnostics) {
+async function rejectSymlinks(root, path, diagnostics, filesystem) {
   const absolute = resolve(root, path);
-  for (const entry of await readdir(absolute, { withFileTypes: true })) {
+  for (
+    const entry of await filesystem.readdir(absolute, { withFileTypes: true })
+  ) {
     const entryPath = `${path}/${entry.name}`;
-    const value = await lstat(resolve(root, entryPath));
+    const value = await filesystem.lstat(resolve(root, entryPath));
     if (value.isSymbolicLink()) {
       diagnostics.push(error(
         "idea.world.symlink",
@@ -89,7 +93,9 @@ async function rejectSymlinks(root, path, diagnostics) {
       ));
       continue;
     }
-    if (value.isDirectory()) await rejectSymlinks(root, entryPath, diagnostics);
+    if (value.isDirectory()) {
+      await rejectSymlinks(root, entryPath, diagnostics, filesystem);
+    }
   }
 }
 
@@ -109,13 +115,14 @@ function requiredTree(objects, path) {
 
 export async function inspectIdeaLayout({
   config: _config,
+  filesystem = DEFAULT_FILESYSTEM,
   root,
   gitRoot = root,
   snapshotTree,
 }) {
   const diagnostics = [];
   const ideasRoot = resolve(root, IDEAS_ROOT);
-  const ideasRootMetadata = await metadata(ideasRoot);
+  const ideasRootMetadata = await metadata(ideasRoot, filesystem);
   if (!ideasRootMetadata) {
     return {
       diagnostics: [error(
@@ -160,7 +167,9 @@ export async function inspectIdeaLayout({
   const aliases = new Map();
   const ideas = [];
   const caseNames = new Map();
-  const entries = (await readdir(ideasRoot, { withFileTypes: true }))
+  const entries = (
+    await filesystem.readdir(ideasRoot, { withFileTypes: true })
+  )
     .sort((left, right) => left.name.localeCompare(right.name));
   const ideaIds = new Set(
     entries.filter((entry) => isValidUlid(entry.name)).map((entry) => entry.name),
@@ -171,7 +180,18 @@ export async function inspectIdeaLayout({
   });
   let worldObjects;
   try {
-    worldObjects = inspectTreePaths(gitRoot, resolvedSnapshotTree, worldPaths);
+    worldObjects = typeof filesystem.snapshotEntry === "function"
+      ? new Map(worldPaths.map((path) => {
+          const entry = filesystem.snapshotEntry(path);
+          return [
+            path,
+            {
+              object: entry?.object ?? null,
+              type: entry?.type ?? "missing",
+            },
+          ];
+        }))
+      : inspectTreePaths(gitRoot, resolvedSnapshotTree, worldPaths);
   } catch (caught) {
     return {
       diagnostics: [error(
@@ -185,7 +205,7 @@ export async function inspectIdeaLayout({
   }
   for (const entry of entries) {
     const folderPath = resolve(ideasRoot, entry.name);
-    const folderMetadata = await lstat(folderPath);
+    const folderMetadata = await filesystem.lstat(folderPath);
     const relativePath = displayPath(root, folderPath);
     const folded = entry.name.toUpperCase();
     const existingCase = caseNames.get(folded);
@@ -219,7 +239,9 @@ export async function inspectIdeaLayout({
     }
 
     const paths = ideaPaths(entry.name);
-    const children = (await readdir(folderPath, { withFileTypes: true }))
+    const children = (
+      await filesystem.readdir(folderPath, { withFileTypes: true })
+    )
       .sort((left, right) => left.name.localeCompare(right.name));
     for (const child of children) {
       if (
@@ -236,7 +258,7 @@ export async function inspectIdeaLayout({
         "Keep only status.yaml, ledger.md, and outer/ at the idea root; put supporting files in their world.",
       ));
     }
-    await requireLedger(root, paths.ledgerPath, diagnostics);
+    await requireLedger(root, paths.ledgerPath, diagnostics, filesystem);
     const requiredDirectories = [
       paths.outerPath,
       paths.innerPath,
@@ -248,14 +270,28 @@ export async function inspectIdeaLayout({
       paths.ideaDocumentPath,
     ];
     const validDirectories = (await Promise.all(
-      requiredDirectories.map((path) => requireDirectory(root, path, diagnostics)),
+      requiredDirectories.map((path) =>
+        requireDirectory(root, path, diagnostics, filesystem)
+      ),
     )).every(Boolean);
     const validDocuments = (await Promise.all(
-      requiredDocuments.map((path) => requireDocument(root, path, diagnostics)),
+      requiredDocuments.map((path) =>
+        requireDocument(root, path, diagnostics, filesystem)
+      ),
     )).every(Boolean);
-    if (validDirectories) await rejectSymlinks(root, paths.outerPath, diagnostics);
+    if (validDirectories) {
+      await rejectSymlinks(
+        root,
+        paths.outerPath,
+        diagnostics,
+        filesystem,
+      );
+    }
 
-    const statusMetadata = await metadata(resolve(root, paths.statusPath));
+    const statusMetadata = await metadata(
+      resolve(root, paths.statusPath),
+      filesystem,
+    );
     if (!statusMetadata || !statusMetadata.isFile() || statusMetadata.isSymbolicLink()) {
       diagnostics.push(error(
         "idea.status.invalid-file",
@@ -269,7 +305,7 @@ export async function inspectIdeaLayout({
     let status;
     try {
       status = parseIdeaStatus(
-        await readFile(resolve(root, paths.statusPath), "utf8"),
+        await filesystem.readFile(resolve(root, paths.statusPath), "utf8"),
         { objectIdLength: repositoryObjectIdLength },
       );
     } catch (caught) {

package/src/idea-metadata.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { extractIdeaTitle, ideaInventoryItem } from "./idea-query.js";
+import { localize } from "./language.js";
+
+export async function readIdeaInventoryItem(root, idea) {
+  const documentPath = idea.worlds.idealRevision.documentPath;
+  try {
+    const source = await readFile(
+      resolve(root, ...documentPath.split("/")),
+      "utf8",
+    );
+    return ideaInventoryItem(idea, extractIdeaTitle(source));
+  } catch (caught) {
+    throw new Error(
+      `Cannot read idea metadata for ${idea.id} at ${documentPath}: ${caught.message}`,
+      { cause: caught },
+    );
+  }
+}
+
+export function metadataFailureObservation(observed, caught, command) {
+  const { ideas: _ideas, ...base } = observed.observation;
+  const problem = {
+    type: "idea-metadata-unavailable",
+    summary: localize(
+      observed.outputLanguage,
+      caught.message,
+      `无法读取 idea metadata：${caught.message}`,
+    ),
+  };
+  return {
+    observation: {
+      ...base,
+      state: "project-setup-required",
+      observedThrough: "configuration",
+      problems: [problem],
+    },
+    responseContext: {
+      nextSteps: localize(
+        observed.outputLanguage,
+        `Repair the reported idea document and retry \`${command}\`.`,
+        `修复报告的 idea document 后，重新运行 \`${command}\`。`,
+      ),
+    },
+  };
+}

package/src/idea-templates.js

@@ -107,3 +107,136 @@ export const LEDGER_TEMPLATE = `# Ledger
 
 - [ ] **D-AC01:** Criterion title
 `;
+
+const CHINESE_IDEA_TEMPLATE = `# 将标题替换为这个 idea 的具体名称
+
+## 意图
+
+<!-- 用一两句话说明期望结果。 -->
+
+## 背景
+
+<!-- 描述当前问题、情境或机会。 -->
+
+## 期望结果
+
+<!-- 描述应当实现的、对外有意义的状态。 -->
+
+## 范围
+
+### 范围内
+
+<!-- 描述这个 idea 包含的内容。 -->
+
+### 范围外
+
+<!-- 描述这个 idea 有意排除的相邻工作。 -->
+
+## 约束
+
+<!-- 记录重要的产品、仓库、兼容性或操作约束。 -->
+
+## 待解决问题
+
+<!-- 记录尚未解决的决定；没有时删除本节。 -->
+`;
+
+const CHINESE_IMPLEMENTATION_TEMPLATE = `# Implementation
+
+## Steps
+
+<!--
+为每个步骤分配稳定的 I-Sxx 标识符和三级标题。
+说明修改内容、边界和重要设计细节。
+不要在本文档中使用任务列表复选框。
+-->
+
+### I-S01: 步骤标题
+
+<!-- 描述该实施步骤。 -->
+
+## Acceptance criteria
+
+<!--
+为每项标准分配稳定的 I-ACxx 标识符和三级标题。
+同时说明可观察结果及其证明方法。
+不要创建单独的验证章节，也不要使用任务列表复选框。
+-->
+
+### I-AC01: 标准标题
+
+<!-- 描述所需结果以及 Agent 如何证明该结果。 -->
+`;
+
+const CHINESE_DEPLOYMENT_TEMPLATE = `# Deployment
+
+## Steps
+
+<!--
+为每个步骤分配稳定的 D-Sxx 标识符和三级标题。
+描述部署或现实世界验证工作。
+不要在本文档中使用任务列表复选框。
+-->
+
+### D-S01: 步骤标题
+
+<!-- 描述该部署或外部验证步骤。 -->
+
+## Acceptance criteria
+
+<!--
+为每项标准分配稳定的 D-ACxx 标识符和三级标题。
+同时说明可观察的外部结果及其证明方法。
+不要创建单独的验证章节，也不要使用任务列表复选框。
+-->
+
+### D-AC01: 标准标题
+
+<!-- 描述所需外部结果以及 Agent 如何证明该结果。 -->
+`;
+
+const CHINESE_LEDGER_TEMPLATE = `# Ledger
+
+## Implementation
+
+### Implementation steps
+
+- [ ] **I-S01:** 步骤标题
+
+### Implementation acceptance criteria
+
+- [ ] **I-AC01:** 标准标题
+
+## Deployment
+
+### Deployment steps
+
+- [ ] **D-S01:** 步骤标题
+
+### Deployment acceptance criteria
+
+- [ ] **D-AC01:** 标准标题
+`;
+
+export function ideaTemplates(contentLanguage) {
+  const normalized = contentLanguage.toLowerCase();
+  if (normalized === "zh" || normalized.startsWith("zh-")) {
+    return {
+      idea: CHINESE_IDEA_TEMPLATE,
+      implementation: CHINESE_IMPLEMENTATION_TEMPLATE,
+      deployment: CHINESE_DEPLOYMENT_TEMPLATE,
+      ledger: CHINESE_LEDGER_TEMPLATE,
+      localized: true,
+      templateLanguage: "zh-CN",
+    };
+  }
+  const localized = normalized === "en" || normalized.startsWith("en-");
+  return {
+    idea: IDEA_TEMPLATE,
+    implementation: IMPLEMENTATION_TEMPLATE,
+    deployment: DEPLOYMENT_TEMPLATE,
+    ledger: LEDGER_TEMPLATE,
+    localized,
+    templateLanguage: "en-US",
+  };
+}