@mycodemap/mycodemap 0.4.2 → 0.5.0

package/scripts/experiments/arcadedb-http-smoke.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+const HELP_TEXT = `
+ArcadeDB HTTP smoke test
+
+Required environment variables:
+  ARCADEDB_HTTP_URL   Base URL, for example http://localhost:2480
+  ARCADEDB_DATABASE   Database name used in /api/v1/command/{database}
+  ARCADEDB_USERNAME   Basic auth username
+  ARCADEDB_PASSWORD   Basic auth password
+
+Optional:
+  ARCADEDB_CYPHER     Cypher query to run
+
+Request:
+  POST {ARCADEDB_HTTP_URL}/api/v1/command/{database}
+  Body: {"language":"cypher","command":"MATCH (n) RETURN count(n) AS total LIMIT 1"}
+  Auth: Authorization: Basic ...
+
+This script is intentionally isolated from shipped runtime code.
+Use --help for offline validation when no ArcadeDB server is available.
+`.trim();
+
+function printHelp() {
+  console.log(HELP_TEXT);
+}
+
+function getRequiredEnv(name) {
+  const value = process.env[name];
+  if (!value || value.trim().length === 0) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value.trim();
+}
+
+async function main() {
+  if (process.argv.includes("--help")) {
+    printHelp();
+    return;
+  }
+
+  let baseUrl;
+  let database;
+  let username;
+  let password;
+
+  try {
+    baseUrl = getRequiredEnv("ARCADEDB_HTTP_URL").replace(/\/+$/, "");
+    database = getRequiredEnv("ARCADEDB_DATABASE");
+    username = getRequiredEnv("ARCADEDB_USERNAME");
+    password = getRequiredEnv("ARCADEDB_PASSWORD");
+  } catch (error) {
+    console.error(String(error instanceof Error ? error.message : error));
+    console.error("Run with --help to see the required contract.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const command = (process.env.ARCADEDB_CYPHER || "MATCH (n) RETURN count(n) AS total LIMIT 1").trim();
+  const endpoint = `${baseUrl}/api/v1/command/${database}`;
+  const authHeader = Buffer.from(`${username}:${password}`, "utf8").toString("base64");
+
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Basic ${authHeader}`,
+    },
+    body: JSON.stringify({
+      language: "cypher",
+      command,
+    }),
+  });
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    console.error(`ArcadeDB HTTP smoke failed: ${response.status} ${response.statusText}`);
+    console.error(text);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("ArcadeDB HTTP smoke succeeded");
+  if (text.trim().length > 0) {
+    console.log(text);
+  }
+}
+
+await main();

package/scripts/validate-docs.js

@@ -226,6 +226,252 @@ function validateAnalyzeDocs(rootDir, failures) {
   failures.push(...collectAnalyzeDocSyncFailures(rootDir));
 }
 
+function validateDesignContractDocs(rootDir, failures) {
+  const readme = readText(rootDir, 'README.md', failures);
+  const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
+  const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
+  const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
+  const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
+  const patternsGuide = readText(rootDir, 'docs/ai-guide/PATTERNS.md', failures);
+  const promptsGuide = readText(rootDir, 'docs/ai-guide/PROMPTS.md', failures);
+  const engineeringGuide = readText(rootDir, 'docs/rules/engineering-with-codex-openai.md', failures);
+  const validationRule = readText(rootDir, 'docs/rules/validation.md', failures);
+  const productSpecsReadme = readText(rootDir, 'docs/product-specs/README.md', failures);
+  const designTemplate = readText(rootDir, 'docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md', failures);
+  const cliIndexSource = readText(rootDir, 'src/cli/index.ts', failures);
+  const designCommandSource = readText(rootDir, 'src/cli/commands/design.ts', failures);
+
+  if (cliIndexSource) {
+    expectIncludes(cliIndexSource, 'program.addCommand(designCommand);', 'src/cli/index.ts design command registration', failures);
+  }
+
+  if (designCommandSource) {
+    validateSnippets(
+      designCommandSource,
+      'src/cli/commands/design.ts command surface',
+      [
+        "new Command('design')",
+        ".command('validate')",
+        ".command('map')",
+        ".command('handoff')",
+        ".command('verify')",
+        'renderDesignMappingResult',
+        'renderDesignVerificationResult',
+        'runDesignHandoff',
+        'runDesignVerify',
+        'DEFAULT_DESIGN_CONTRACT_PATH',
+        'JSON 格式输出'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (readme) {
+    validateSnippets(
+      readme,
+      'README.md design contract baseline',
+      [
+        'mycodemap design validate mycodemap.design.md --json',
+        'mycodemap design map mycodemap.design.md --json',
+        'mycodemap design handoff mycodemap.design.md --json',
+        'mycodemap design verify mycodemap.design.md --json',
+        'docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md',
+        '`mycodemap.design.md`',
+        '`design validate → design map → design handoff → design verify`'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (aiGuide) {
+    validateSnippets(
+      aiGuide,
+      'AI_GUIDE.md design contract baseline',
+      [
+        'design validate mycodemap.design.md --json',
+        'design map mycodemap.design.md --json',
+        'design handoff mycodemap.design.md --json',
+        'design verify mycodemap.design.md --json',
+        '`mycodemap.design.md`',
+        'interface DesignValidateOutput {',
+        'interface DesignMapOutput {',
+        'interface DesignHandoffOutput {',
+        'interface DesignVerificationOutput {'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (claudeGuide) {
+    validateSnippets(
+      claudeGuide,
+      'CLAUDE.md design retrieval guidance',
+      [
+        'node dist/cli/index.js design validate [file] --json',
+        'node dist/cli/index.js design map [file] --json',
+        'node dist/cli/index.js design handoff [file] --json',
+        'node dist/cli/index.js design verify [file] --json'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (commandsGuide) {
+    validateSnippets(
+      commandsGuide,
+      'docs/ai-guide/COMMANDS.md design contract baseline',
+      [
+        '## design - 设计契约输入、范围映射与验证',
+        'mycodemap design validate mycodemap.design.md --json',
+        'mycodemap design map mycodemap.design.md --json',
+        'mycodemap design handoff mycodemap.design.md --json',
+        'mycodemap design verify mycodemap.design.md --json',
+        '`mycodemap.design.md`',
+        '### 必填 sections',
+        '### map',
+        '### handoff',
+        '### verify',
+        'no-candidates'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (outputGuide) {
+    validateSnippets(
+      outputGuide,
+      'docs/ai-guide/OUTPUT.md design validate schema',
+      [
+        '## design validate 命令输出结构',
+        '## design map 命令输出结构',
+        '## design handoff 命令输出结构',
+        '## design verify 命令输出结构',
+        'type DesignContractDiagnosticCode =',
+        'interface DesignValidateOutput {',
+        'interface DesignMapOutput {',
+        'interface DesignHandoffOutput {',
+        'interface DesignVerificationOutput {',
+        'unknowns: string[];',
+        'diagnostics: DesignMappingDiagnostic[];',
+        'readyForExecution: boolean;',
+        'approvals: Array<DesignHandoffTraceItem & {',
+        'assumptions: DesignHandoffTraceItem[];',
+        'openQuestions: DesignHandoffTraceItem[];',
+        'type DesignVerificationStatus =',
+        'type DesignDriftKind =',
+        'checklist: Array<{',
+        'drift: Array<{',
+        '"code": "handoff-missing"',
+        '"code": "missing-section"',
+        '"code": "high-risk-scope"',
+        '"code": "review-required"'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (patternsGuide) {
+    validateSnippets(
+      patternsGuide,
+      'docs/ai-guide/PATTERNS.md design/workflow baseline',
+      [
+        'node dist/cli/index.js design validate mycodemap.design.md --json',
+        'node dist/cli/index.js design map mycodemap.design.md --json',
+        'node dist/cli/index.js design handoff mycodemap.design.md --json',
+        'node dist/cli/index.js design verify mycodemap.design.md --json',
+        '`design validate → design map → design handoff → design verify`',
+        '`workflow` 仍只保留 `find` / `read` / `link` / `show` 四阶段'
+      ],
+      [
+        '5. `commit` - 提交验证',
+        '6. `ci` - CI 验证'
+      ],
+      failures
+    );
+  }
+
+  if (promptsGuide) {
+    validateSnippets(
+      promptsGuide,
+      'docs/ai-guide/PROMPTS.md design contract prompt',
+      [
+        'cp docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md mycodemap.design.md',
+        'node dist/cli/index.js design validate mycodemap.design.md --json'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (engineeringGuide) {
+    validateSnippets(
+      engineeringGuide,
+      'docs/rules/engineering-with-codex-openai.md design command guardrail',
+      [
+        '`node dist/cli/index.js design validate mycodemap.design.md --json`',
+        '`node dist/cli/index.js design map mycodemap.design.md --json`',
+        '`node dist/cli/index.js design handoff mycodemap.design.md --json`',
+        '`node dist/cli/index.js design verify mycodemap.design.md --json`',
+        '`candidates` / `unknowns` / `diagnostics`',
+        '`readyForExecution` / `approvals` / `assumptions` / `openQuestions`',
+        '`checklist` / `drift` / `diagnostics` / `readyForExecution`',
+        '`docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md`'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (productSpecsReadme) {
+    validateSnippets(
+      productSpecsReadme,
+      'docs/product-specs/README.md design template index',
+      [
+        '`DESIGN_CONTRACT_TEMPLATE.md`'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (validationRule) {
+    validateSnippets(
+      validationRule,
+      'docs/rules/validation.md design verification baseline',
+      [
+        '`design validate` / `design map` / `design handoff` / `design verify`',
+        '`design validate → design map → design handoff → design verify`',
+        'design verify mycodemap.design.md --json',
+        'review-needed 与 blocker 退出语义'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (designTemplate) {
+    validateSnippets(
+      designTemplate,
+      'docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md',
+      [
+        '保存为 `mycodemap.design.md`',
+        '## Goal',
+        '## Constraints',
+        '## Acceptance Criteria',
+        '## Non-Goals'
+      ],
+      [],
+      failures
+    );
+  }
+}
+
 function validatePositioningBaselineDocs(rootDir, failures) {
   const readme = readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
@@ -938,6 +1184,7 @@ function validateDocs(rootDir) {
   validatePluginRuntimeDocs(rootDir, failures);
   validateGraphStorageDocs(rootDir, failures);
   validateAnalyzeDocs(rootDir, failures);
+  validateDesignContractDocs(rootDir, failures);
   validateTestingDocs(rootDir, failures);
   validateWorkflowAndDiscoveryDocs(rootDir, failures);
   validateProductSpecsDocs(rootDir, failures);