From 8f481439d1c97980543234252f3361d09bbea396 Mon Sep 17 00:00:00 2001 From: zack-dev-cm <112114097+zack-dev-cm@users.noreply.github.com> Date: Fri, 13 Nov 2026 10:44:02 +0400 Subject: [PATCH 1/3] ci: enforce source, docs and environment guards Signed-off-by: zack-dev-cm <112114097+zack-dev-cm@users.noreply.github.com> --- .env.example | 144 ++++++++++++ .github/workflows/ci.yml | 50 ++--- AGENTS.md | 2 +- CHANGELOG.md | 2 +- package.json | 3 + scripts/check-env-example.mjs | 271 +++++++++++++++-------- scripts/ci-changes.mjs | 29 +++ scripts/docs-sync.state.json | 6 + scripts/docs-sync.ts | 92 ++++++++ src/cli/compose-control.ts | 2 +- src/cli/connect/dsh.ts | 4 +- src/functions/capture.ts | 2 - src/functions/diagnostics.ts | 1 - src/functions/export-import.ts | 1 - src/functions/image-quota-cleanup.ts | 1 - src/functions/retention.ts | 16 -- src/functions/skill-extract.ts | 2 +- src/functions/slots.ts | 17 +- src/functions/working-memory.ts | 2 +- src/health/monitor.ts | 9 +- src/providers/openai.ts | 1 - src/state/reranker.ts | 4 +- src/triggers/api.ts | 8 +- src/types.ts | 1 + test/ci-changes.test.ts | 84 +++++++ test/ci-source-contracts.test.ts | 105 +++++++++ test/env-example-bindings.test.ts | 79 +++++++ test/env-example-check.test.ts | 66 ++++++ test/env-example-process-imports.test.ts | 40 ++++ test/health-monitor-cpu.test.ts | 1 + 30 files changed, 879 insertions(+), 166 deletions(-) create mode 100644 scripts/ci-changes.mjs create mode 100644 test/ci-changes.test.ts create mode 100644 test/ci-source-contracts.test.ts create mode 100644 test/env-example-bindings.test.ts create mode 100644 test/env-example-check.test.ts create mode 100644 test/env-example-process-imports.test.ts diff --git a/.env.example b/.env.example index a9495aee55..03bd1dcee6 100644 --- a/.env.example +++ b/.env.example @@ -257,3 +257,147 @@ # ----------------------------------------------------------------------------- # OBSIDIAN_AUTO_EXPORT=true # Auto-export memories to an Obsidian vault on every consolidation + +# Additional runtime and integration configuration +# These commented entries document existing readers without changing defaults. + +# Agent isolation mode: shared or isolated; used together with AGENT_ID. +#AGENTMEMORY_AGENT_SCOPE= + +# Commit SHA override for integrations invoking the post-commit hook manually. +#AGENTMEMORY_COMMIT_SHA= + +# Minimum time between consolidation runs, in milliseconds. +#AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS= + +# Use explicit to disable fallback to locally saved credentials. +#AGENTMEMORY_CREDENTIAL_MODE= + +# Working-directory fallback for manually invoked post-commit hooks. +#AGENTMEMORY_CWD= + +# Set to 1 to disable the managed Compose restart policy. +#AGENTMEMORY_DISABLE_COMPOSE_RESTART= + +# Window for session follow-up scheduling, in seconds. +#AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS= + +# Maximum total managed image-store size, in bytes. +#AGENTMEMORY_IMAGE_STORE_MAX_BYTES= + +# Override the worker metrics port chosen by the CLI. +#AGENTMEMORY_METRICS_PORT= + +# Override the project name derived by capture hooks. +#AGENTMEMORY_PROJECT_NAME= + +# Legacy provider override; noop disables session summarization. +#AGENTMEMORY_PROVIDER= + +# Override the base directory for local runtime files. +#AGENTMEMORY_RUNTIME_DIR= + +# Session identifier fallback for manually invoked post-commit hooks. +#AGENTMEMORY_SESSION_ID= + +# State-worker checkpoint period, in milliseconds. +#AGENTMEMORY_STATE_SAVE_INTERVAL_MS= + +# Set to 1 or true to suppress the premium-model cost warning. +#AGENTMEMORY_SUPPRESS_COST_WARNING= + +# Enable verbose CLI and worker diagnostic logging. +#AGENTMEMORY_VERBOSE= + +# Viewer bind address; the default is 127.0.0.1. +#AGENTMEMORY_VIEWER_HOST= + +# Directory containing local state and http worker executables. +#AGENTMEMORY_WORKER_BIN_DIR= + +# Agent identifier used by scoped memory operations. +#AGENT_ID= + +# Enable diagnostic logging for the Cursor workspace adapter. +#AM_CURSOR_DEBUG= + +# Background auto-forget is enabled unless set to false. +#AUTO_FORGET_ENABLED= + +# Auto-forget interval in milliseconds; use an integer (default 3600000). +#AUTO_FORGET_INTERVAL_MS= + +# Background consolidation interval in milliseconds; use a positive integer. +#CONSOLIDATION_INTERVAL_MS= + +# Override the iii-engine WebSocket address. +#III_URL= + +# Background insight decay is enabled unless set to false. +#INSIGHT_DECAY_ENABLED= + +# Background lesson decay is enabled unless set to false. +#LESSON_DECAY_ENABLED= + +# Override the MiniMax Anthropic-compatible API base URL. +#MINIMAX_BASE_URL= + +# Azure OpenAI API version for chat and embeddings. +#OPENAI_API_VERSION= + +# Optional reasoning_effort value sent to compatible chat endpoints. +#OPENAI_REASONING_EFFORT= + +# OpenAI-compatible request timeout, in milliseconds. +#OPENAI_TIMEOUT_MS= + +# Requested output dimensions for the selected OpenRouter embedding model. +#OPENROUTER_EMBEDDING_DIMENSIONS= + +# Embedding batch size used when rebuilding search indexes. +#REBUILD_EMBED_BATCH_SIZE= + +# Set to true to enable the optional cross-encoder reranker. +#RERANK_ENABLED= + +# Comma-separated Host header allowlist override for the viewer. +#VIEWER_ALLOWED_HOSTS= + +# Override the Claude Code configuration directory used by connect. +#CLAUDE_CONFIG_DIR= + +# Override the Cline MCP settings file used by connect. +#CLINE_MCP_SETTINGS_PATH= + +# Override the Copilot CLI configuration directory used by connect. +#COPILOT_HOME= + +# Override the DSH configuration directory used by connect. +#DSH_HOME= + +# Select a suffixed Hermes data directory when HERMES_HOME is unset. +#HERMES_DATA_DIR_SUFFIX= + +# Override the Hermes configuration and data directory used by connect. +#HERMES_HOME= + +# Oh My Pi profile fallback when PI_PROFILE is unset. +#OMP_PROFILE= + +# Override the OpenClaw configuration file used by connect. +#OPENCLAW_CONFIG_PATH= + +# Override the OpenClaw home directory used by connect. +#OPENCLAW_HOME= + +# Override the OpenClaw state directory used by connect. +#OPENCLAW_STATE_DIR= + +# Override the Pi coding-agent configuration directory. +#PI_CODING_AGENT_DIR= + +# Override the Oh My Pi configuration directory used by connect. +#PI_CONFIG_DIR= + +# Select the Pi or Oh My Pi configuration profile. +#PI_PROFILE= diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2806b98182..642c0a6177 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,35 +1,11 @@ name: CI -# `paths-ignore` keeps doc-only / website / README / CHANGELOG churn from -# burning runner minutes. Source / config / workflow changes always run. -# `workflow_dispatch` gives a manual re-run button for flake debugging. +# Cheap guards run for every change; only source changes need the test matrix. on: push: branches: [main] - paths-ignore: - - "README.md" - - "CHANGELOG.md" - - "AGENTS.md" - - "ROADMAP.md" - - "website/**" - - "docs/**" - - "assets/**" - - "deploy/**/README.md" - - "**/*.md" - - "**/*.mdx" pull_request: branches: [main] - paths-ignore: - - "README.md" - - "CHANGELOG.md" - - "AGENTS.md" - - "ROADMAP.md" - - "website/**" - - "docs/**" - - "assets/**" - - "deploy/**/README.md" - - "**/*.md" - - "**/*.mdx" workflow_dispatch: # Cancel in-flight PR runs when a force-push lands. Keep push runs to @@ -42,7 +18,29 @@ permissions: contents: read jobs: + quality: + runs-on: ubuntu-latest + outputs: + run_tests: ${{ steps.changes.outputs.run_tests }} + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + fetch-depth: 0 + - uses: actions/setup-node@v6 + with: + node-version: 22 + - id: changes + run: node scripts/ci-changes.mjs + - run: npm install --legacy-peer-deps --no-audit --no-fund + - run: npm run typecheck + - run: npm run skills:check + - run: npm run docs:check + - run: npm run env:check + test: + needs: quality + if: needs.quality.outputs.run_tests == 'true' runs-on: ${{ matrix.os }} strategy: # Don't bail the whole matrix on one cell's failure — we want to @@ -73,4 +71,4 @@ jobs: - run: npm run build - run: npm run skills:check - run: npx tsc --noEmit --project tsconfig.eval.json - - run: npm test + - run: npm run test:ci diff --git a/AGENTS.md b/AGENTS.md index c2e9d97cc5..eb4ff24f9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -113,5 +113,5 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - 147 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 17 skills -- 322+ iii functions +- 323+ iii functions - 4,900+ tests diff --git a/CHANGELOG.md b/CHANGELOG.md index 16a6992fab..ee5a01a74a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -855,7 +855,7 @@ Six PRs landed since v0.9.12 — `.env.example` discovery shipped (#372), CJK BM - **`agentmemory init` command**. Copies the bundled `.env.example` to `~/.agentmemory/.env` if that file doesn't already exist; refuses to overwrite an existing config and prints a diff command pointing at the latest template. Wired into the CLI help block alongside `status` / `doctor` / `demo` / `upgrade` / `mcp` / `import-jsonl`. -- **CI sync-checker for `.env.example`** (`scripts/check-env-example.mjs`). Walks every `.ts` / `.mts` / `.mjs` / `.js` file under `src/`, extracts `process.env["KEY"]` / `env["KEY"]` / `getMergedEnv()["KEY"]` / `getEnvVar("KEY")` references, and fails CI when `src/` reads an env var the template doesn't document (or vice versa). Plugged into `.github/workflows/ci.yml` after `npm test`. Initial bootstrap: 60 keys in sync. +- **CI sync-checker for `.env.example`** (`scripts/check-env-example.mjs`). Walks every `.ts` / `.mts` / `.mjs` / `.js` file under `src/`, extracts `process.env["KEY"]` / `env["KEY"]` / `getMergedEnv()["KEY"]` / `getEnvVar("KEY")` references, and fails CI when `src/` reads an env var the template doesn't document (or vice versa). Runs as `npm run env:check` in the always-on `quality` job of `.github/workflows/ci.yml`, before the conditional test matrix. Initial bootstrap: 60 keys in sync. - **CJK tokenizer for BM25 search** ([#344](https://github.com/rohitg00/agentmemory/issues/344), PR [#362](https://github.com/rohitg00/agentmemory/pull/362)). New `src/state/cjk-segmenter.ts` detects CJK input by Unicode block and routes to `@node-rs/jieba` (Chinese, native, no model download), `tiny-segmenter` (Japanese, pure JS, ~25 KB), or rule-based syllable-block split (Korean). Both segmenters declared in `optionalDependencies` so the base install stays lean; soft-fail with a one-time stderr hint when the dep is missing. Order-preserving single-pass tokenization across mixed CJK + non-CJK runs (regression test for `"abc 메모리 def 项目 ghi"` returns `["abc","메모리","def","项目","ghi"]`). diff --git a/package.json b/package.json index 5540b52f8f..4d89f3e915 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,9 @@ "migrate": "node dist/functions/migrate.js", "pretest": "npm run build", "test": "vitest run --exclude test/integration.test.ts", + "test:ci": "vitest run --exclude test/integration.test.ts", + "typecheck": "tsc --noEmit --project tsconfig.json", + "env:check": "node scripts/check-env-example.mjs", "test:watch": "vitest --exclude test/integration.test.ts", "test:integration": "vitest run test/integration.test.ts", "test:all": "vitest run", diff --git a/scripts/check-env-example.mjs b/scripts/check-env-example.mjs index ae5ea857a8..886c2981a6 100644 --- a/scripts/check-env-example.mjs +++ b/scripts/check-env-example.mjs @@ -1,101 +1,196 @@ #!/usr/bin/env node -// -// Sync-check: every env var read by `src/` MUST be documented in -// `.env.example`. Runs in CI as a soft guard rail — keeps `.env.example` -// from drifting behind real config-surface additions. -// -// Usage: -// node scripts/check-env-example.mjs -// -// Returns 0 when in sync, 1 with a diff when out of sync. +import { readFileSync, readdirSync } from "node:fs"; +import { join, relative } from "node:path"; +import { fileURLToPath } from "node:url"; +import ts from "typescript"; -import { readFileSync, readdirSync, statSync } from "node:fs"; -import { join } from "node:path"; - -const ROOT = new URL("..", import.meta.url).pathname; -const SRC = join(ROOT, "src"); -const ENV_FILE = join(ROOT, ".env.example"); - -// Env vars read by the runtime but NOT user-facing config — these are -// either process-injected (HOME, PATH, USERPROFILE), set by the build / -// wrapper (NODE_*, npm_*), or set by tests (VITEST, *_TEST_*). Skipping -// them keeps `.env.example` a documented config surface rather than an -// inventory of every getenv anywhere in the codebase. +const ROOT = fileURLToPath(new URL("..", import.meta.url)); const RUNTIME_ONLY = new Set([ - "HOME", - "PATH", - "USERPROFILE", - "NODE_ENV", - "AGENTMEMORY_SDK_CHILD", + "HOME", "PATH", "USERPROFILE", "NODE_ENV", "AGENTMEMORY_SDK_CHILD", + "APPDATA", "CI", "COMSPEC", "EDITOR", "NO_COLOR", "PWD", "SYSTEMROOT", + "VISUAL", "XDG_CONFIG_HOME", "XDG_DATA_HOME", + // Private worker protocol and release-gate fault injection are not user settings. + "AGENTMEMORY_CAPTURE_DRAIN_CHILD", "AGENTMEMORY_SESSION_END_WORKER", + "AGENTMEMORY_MCP_STDIO__", "AGENTMEMORY_RELEASE_GATE_FAIL_OBSERVE__", + "AM_HOOK_INPUT_FILE", "AM_HOOK_WORKER", "III_COMPOSE_FILE", + // The host agent injects these workspace and session markers. + "COPILOT_AGENT_SESSION_ID", "COPILOT_CLI", "COPILOT_PLUGIN_ROOT", + "CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "CURSOR_WORKSPACE_FOLDER", + "CURSOR_WORKSPACE_ROOT", "CURSOR_WORKSPACE_LABEL", "DEVIN_PROJECT_DIR", + "DROID_PLUGIN_ROOT", "FACTORY_PROJECT_DIR", "VSCODE_CWD", ]); - -// Walk src/ for .ts / .mts / .mjs / .js files (excluding `.d.ts` declarations -// and dotfile dirs / node_modules). test/ lives outside src/ so it never enters. -function walk(dir) { - const out = []; - for (const entry of readdirSync(dir)) { - const full = join(dir, entry); - const s = statSync(full); - if (s.isDirectory()) { - if (entry === "node_modules" || entry.startsWith(".")) continue; - out.push(...walk(full)); - } else if (/\.(ts|mts|mjs|js)$/.test(entry) && !entry.endsWith(".d.ts")) { - out.push(full); +// The pinned iii SDK consumes this supported setting outside src/. +const EXTERNAL_SETTINGS = new Set(["III_TELEMETRY_ENABLED"]); +function files(dir) { + return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + if (entry.name.startsWith(".") || entry.name === "node_modules") return []; + const path = join(dir, entry.name); + if (entry.isDirectory()) return files(path); + return entry.isFile() && /\.(?:ts|mts|mjs|js)$/.test(entry.name) && !/\.d\.(?:ts|mts)$/.test(entry.name) ? [path] : []; + }); +} +const paths = files(join(ROOT, "src")); +// Compiler bindings distinguish scoped names and reader aliases without executing source. +const program = ts.createProgram(paths, { target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.NodeNext, moduleResolution: ts.ModuleResolutionKind.NodeNext, noResolve: true, noLib: true, types: [], allowJs: true, noEmit: true }); +const checker = program.getTypeChecker(); +const sources = paths.map((path) => program.getSourceFile(path)); +const functions = [], calls = []; +function visit(node, fn) { fn(node); ts.forEachChild(node, (child) => visit(child, fn)); } +function bodyNodes(node, fn) { + fn(node); + ts.forEachChild(node, (child) => { if (!ts.isFunctionLike(child)) bodyNodes(child, fn); }); +} +for (const source of sources) visit(source, (node) => { + if ((ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isMethodDeclaration(node)) && node.body) functions.push(node); + if (ts.isCallExpression(node) || ts.isNewExpression(node)) calls.push(node); +}); +function unwrap(node) { + while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node))) node = node.expression; + return node; +} +function symbol(node) { + const value = node && checker.getSymbolAtLocation(node); + return value?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(value) : value; +} +function target(node, seen = new Set()) { + node = unwrap(node); + if (!node) return undefined; + if (ts.isFunctionLike(node) && node.body) return node; + const value = symbol(node); + if (!value || seen.has(value)) return undefined; + seen.add(value); + for (const declaration of value.declarations ?? []) { + if (ts.isFunctionLike(declaration) && declaration.body) return declaration; + if ((ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration)) && declaration.initializer) { + const fn = target(declaration.initializer, seen); + if (fn) return fn; } } - return out; } - -// Multiple patterns: -// process.env["KEY"] — direct access -// env["KEY"] — local alias inside detectProvider, etc. -// getEnvVar("KEY") — helper from src/config.ts -// env: ProcessEnv → env.KEY — caught as `env["KEY"]` only; if you add -// a dotted-access path, extend the regex. -const PATTERNS = [ - // Direct map index: process.env["KEY"], env["KEY"], getMergedEnv()["KEY"]. - // The trailing `]\s*` form covers `…)["KEY"]` and `…env["KEY"]`. - /\[\s*"([A-Z][A-Z0-9_]+)"\s*\]/g, - /getEnvVar\(\s*"([A-Z][A-Z0-9_]+)"\s*\)/g, -]; -const used = new Set(); -for (const file of walk(SRC)) { - const text = readFileSync(file, "utf8"); - for (const pat of PATTERNS) { - pat.lastIndex = 0; - let m; - while ((m = pat.exec(text)) !== null) { - const name = m[1]; - if (!RUNTIME_ONLY.has(name)) used.add(name); - } +function constant(node, seen = new Set()) { + node = unwrap(node); + if (!node) return undefined; + if (ts.isStringLiteralLike(node)) return node.text; + const value = symbol(node); + if (!value || seen.has(value)) return undefined; + seen.add(value); + for (const declaration of value.declarations ?? []) { + if (ts.isVariableDeclaration(declaration) && (declaration.parent.flags & ts.NodeFlags.Const)) return constant(declaration.initializer, seen); } } - -const envText = readFileSync(ENV_FILE, "utf8"); -const documented = new Set(); -for (const line of envText.split("\n")) { - const m = line.match(/^#?\s*([A-Z][A-Z0-9_]+)=/); - if (m) documented.add(m[1]); +function builtinImport(node, kind) { + if (!ts.isIdentifier(node)) return false; + const value = checker.getSymbolAtLocation(node); + return value?.declarations?.some((declaration) => { + let current = declaration; + while (current && !ts.isImportDeclaration(current)) current = current.parent; + if (!current || !["node:process", "process"].includes(current.moduleSpecifier.text)) return false; + if (kind === "process") return ts.isImportClause(declaration) || ts.isNamespaceImport(declaration) || (ts.isImportSpecifier(declaration) && (declaration.propertyName ?? declaration.name).text === "default"); + return ts.isImportSpecifier(declaration) && (declaration.propertyName ?? declaration.name).text === "env"; + }) ?? false; } - -const missing = [...used].filter((k) => !documented.has(k)).sort(); -const orphan = [...documented].filter((k) => !used.has(k)).sort(); - -if (missing.length === 0 && orphan.length === 0) { - console.log(`env-example: in sync (${used.size} keys documented)`); - process.exit(0); +function processObject(node, seen = new Set()) { + node = unwrap(node); + if (!node || !ts.isIdentifier(node)) return false; + if (builtinImport(node, "process")) return true; + const value = checker.getSymbolAtLocation(node); + if (!value?.declarations?.length) return node.text === "process"; + if (seen.has(value)) return false; + seen.add(value); + return value.declarations.some((declaration) => { + return ts.isVariableDeclaration(declaration) && (declaration.parent.flags & ts.NodeFlags.Const) && processObject(declaration.initializer, seen); + }); } - -if (missing.length > 0) { - console.error( - `env-example: MISSING from .env.example — add documentation for these keys:`, - ); - for (const k of missing) console.error(` - ${k}`); +const environmentParameters = new Set(), environmentReturns = new Set(); +function environment(node, seen = new Set()) { + node = unwrap(node); + if (!node) return false; + if (builtinImport(node, "env")) return true; + if (ts.isPropertyAccessExpression(node) && node.name.text === "env" && processObject(node.expression)) return true; + if (ts.isCallExpression(node) && environmentReturns.has(target(node.expression))) return true; + if (ts.isBinaryExpression(node) && [ts.SyntaxKind.QuestionQuestionToken, ts.SyntaxKind.BarBarToken].includes(node.operatorToken.kind)) return environment(node.left, new Set(seen)) || environment(node.right, new Set(seen)); + if (ts.isObjectLiteralExpression(node)) return node.properties.some((property) => ts.isSpreadAssignment(property) && environment(property.expression, new Set(seen))); + const value = symbol(node); + if (!value || seen.has(value)) return false; + if (environmentParameters.has(value)) return true; + seen.add(value); + for (const declaration of value.declarations ?? []) { + if (declaration.type?.getText().replace(/\s/g, "") === "NodeJS.ProcessEnv") return true; + if (declaration.initializer && environment(declaration.initializer, new Set(seen))) return true; + } + return false; +} +let changed; +do { + changed = false; + for (const call of calls) { + const fn = target(call.expression); + if (!fn) continue; + for (let i = 0; i < fn.parameters.length; i++) { + const parameter = symbol(fn.parameters[i].name); + if (parameter && !environmentParameters.has(parameter) && environment(call.arguments?.[i])) { environmentParameters.add(parameter); changed = true; } + } + } + for (const fn of functions) if (!environmentReturns.has(fn)) { + let returnsEnvironment = !ts.isBlock(fn.body) && environment(fn.body); + bodyNodes(fn.body, (node) => { if (ts.isReturnStatement(node) && environment(node.expression)) returnsEnvironment = true; }); + if (returnsEnvironment) { environmentReturns.add(fn); changed = true; } + } +} while (changed); +function readKey(node) { + if (!(ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) || !environment(node.expression)) return undefined; + if (ts.isDeleteExpression(node.parent)) return undefined; + if (ts.isBinaryExpression(node.parent) && node.parent.left === node && node.parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) return undefined; + return ts.isPropertyAccessExpression(node) ? node.name : node.argumentExpression; +} +const readers = new Map(); +function positions(expression) { + const fn = target(expression); + if (fn) return readers.get(fn) ?? []; + return ts.isIdentifier(expression) && expression.text === "getEnvVar" && !symbol(expression)?.declarations?.length ? [0] : []; +} +do { + changed = false; + for (const fn of functions) { + const result = readers.get(fn) ?? new Set(); + const prior = result.size; + bodyNodes(fn.body, (node) => { + const keys = [readKey(node)]; + if (ts.isCallExpression(node)) for (const index of positions(node.expression)) keys.push(node.arguments[index]); + for (const key of keys) if (key && ts.isIdentifier(key)) { + const value = symbol(key); + const index = fn.parameters.findIndex((parameter) => symbol(parameter.name) === value); + if (index >= 0) result.add(index); + } + }); + if (result.size > prior) { readers.set(fn, result); changed = true; } + } +} while (changed); +const used = new Map(); +function record(key, node) { + if (!key || !/^[A-Z][A-Z0-9_]*$/.test(key) || RUNTIME_ONLY.has(key)) return; + const source = node.getSourceFile(), { line } = source.getLineAndCharacterOfPosition(node.getStart(source)); + if (!used.has(key)) used.set(key, new Set()); + used.get(key).add(`${relative(ROOT, source.fileName)}:${line + 1}`); } -if (orphan.length > 0) { - console.error( - `env-example: ORPHAN in .env.example — no longer read by src/, remove or move to runtime-only allowlist:`, - ); - for (const k of orphan) console.error(` - ${k}`); +for (const source of sources) visit(source, (node) => { + const key = readKey(node); + if (key) record(ts.isPropertyAccessExpression(node) ? node.name.text : constant(key), node); + if (ts.isCallExpression(node)) for (const index of positions(node.expression)) record(constant(node.arguments[index]), node); + if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && environment(node.initializer)) for (const binding of node.name.elements) { + if (!binding.dotDotDotToken) record((binding.propertyName ?? binding.name).text, binding); + } +}); +const documented = new Set(); +for (const line of readFileSync(join(ROOT, ".env.example"), "utf8").split("\n")) { + const match = line.match(/^#?\s*([A-Z][A-Z0-9_]*)=/); + if (match) documented.add(match[1]); } -process.exit(1); +const missing = [...used.keys()].filter((name) => !documented.has(name)).sort(); +const orphan = [...documented].filter((name) => !used.has(name) && !EXTERNAL_SETTINGS.has(name)).sort(); +if (process.argv.includes("--json")) console.log(JSON.stringify({ missing, orphan, readers: Object.fromEntries([...used].sort().map(([name, locations]) => [name, [...locations]])), runtimeOnly: [...RUNTIME_ONLY], externalSettings: [...EXTERNAL_SETTINGS] }, null, 2)); +else if (missing.length || orphan.length) { + for (const name of missing) console.error(`env-example: MISSING ${name} (${[...used.get(name)].join(", ")})`); + for (const name of orphan) console.error(`env-example: ORPHAN ${name}`); +} else console.log(`env-example: in sync (${used.size} source settings documented)`); +process.exitCode = missing.length || orphan.length ? 1 : 0; diff --git a/scripts/ci-changes.mjs b/scripts/ci-changes.mjs new file mode 100644 index 0000000000..76e88877ff --- /dev/null +++ b/scripts/ci-changes.mjs @@ -0,0 +1,29 @@ +#!/usr/bin/env node +import { appendFileSync, readFileSync } from "node:fs"; +import { execFileSync } from "node:child_process"; + +const docsOnly = (path) => /\.mdx?$/.test(path) || /^(?:docs|assets|website)\//.test(path); +const sha = (value) => typeof value === "string" && /^(?:[a-f\d]{40}|[a-f\d]{64})$/i.test(value); + +function classify() { + const name = process.env.GITHUB_EVENT_NAME; + if (name === "workflow_dispatch") return { runTests: true, reason: "manual dispatch" }; + if (name !== "push" && name !== "pull_request") return { runTests: true, reason: "unrecognized event" }; + try { + const event = JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, "utf8")); + const base = name === "pull_request" ? event.pull_request?.base?.sha : event.before; + const head = process.env.GITHUB_SHA; + if (!sha(base) || !sha(head) || /^0+$/.test(base)) return { runTests: true, reason: "no comparable base" }; + const paths = execFileSync("git", ["diff", "--name-only", "--no-renames", "-z", base, head, "--"], { + encoding: "utf8", maxBuffer: 16 * 1024 * 1024, + }).split("\0").filter(Boolean); + return { runTests: paths.some((path) => !docsOnly(path)), reason: "changed paths", paths }; + } catch { + // Missing history or malformed event data must never silently skip source tests. + return { runTests: true, reason: "change detection unavailable" }; + } +} + +const result = classify(); +if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `run_tests=${result.runTests}\n`); +console.log(JSON.stringify(result)); diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json index 7f6afbb042..5f9beba63a 100644 --- a/scripts/docs-sync.state.json +++ b/scripts/docs-sync.state.json @@ -33,6 +33,12 @@ ], "kvScopes": [ "65" + ], + "mcpResources": [ + "6" + ], + "mcpPrompts": [ + "3" ] }, "engineVersion": "0.25.1" diff --git a/scripts/docs-sync.ts b/scripts/docs-sync.ts index 7c38f1196a..4043abd859 100644 --- a/scripts/docs-sync.ts +++ b/scripts/docs-sync.ts @@ -3,6 +3,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { ESSENTIAL_TOOLS, getAllTools } from "../src/mcp/tools-registry.js"; +import ts from "typescript"; const ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); const STATE_PATH = "scripts/docs-sync.state.json"; @@ -56,6 +57,18 @@ function countFallbackTools(): number { return (body.slice(0, body.indexOf("]);")).match(/"memory_\w+"/g) ?? []).length; } +function countMcpEntries(name: string): string | null { + const path = "src/mcp/server.ts"; + const source = ts.createSourceFile(path, read(path), ts.ScriptTarget.Latest, true); + const counts: number[] = []; + const visit = (node: ts.Node): void => { + if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer && ts.isArrayLiteralExpression(node.initializer) && node.initializer.elements.every(ts.isObjectLiteralExpression)) counts.push(node.initializer.elements.length); + ts.forEachChild(node, visit); + }; + visit(source); + return counts.length === 1 ? String(counts[0]) : null; +} + function sourceFiles(): string[] { return trackedFiles().filter((f) => f.startsWith("src/") && f.endsWith(".ts")); } @@ -81,6 +94,8 @@ const TOOL_NOUNS = [ ]; const FACTS: Fact[] = [ + { key: "mcpResources", label: "MCP resources", value: () => countMcpEntries("MCP_RESOURCES"), nouns: ["MCP resources"] }, + { key: "mcpPrompts", label: "MCP prompts", value: () => countMcpEntries("MCP_PROMPTS"), nouns: ["MCP prompts"] }, { key: "mcpTools", label: "MCP tools", @@ -227,6 +242,61 @@ function formatLike(matched: string, next: string): string { return digits.replace(/\B(?=(\d{3})+(?!\d))/g, separator); } +function syncBadgeNumber(value: string, next: string): string { + return value.replace(/\d+(?:[,.\u00a0\u202f ]\d{3})*\+?/g, (number) => + `${formatLike(number, next)}${next.endsWith("+") ? "+" : ""}`, + ); +} + +function syncBadge(text: string, next: string): string { + return text + .replace(/>(\d+(?:[,.\u00a0\u202f ]\d{3})*\+?) `>${syncBadgeNumber(number, next)}<`) + .replace(/(aria-label=")([^"]*)(")/g, (_match, prefix: string, label: string, suffix: string) => `${prefix}${syncBadgeNumber(label, next)}${suffix}`); +} + +function currentCount(matched: string, key: string, state: State): string { + const next = state.facts[key]?.[0]; + if (!next) throw new Error(`Could not compute current ${key}.`); + return `${formatLike(matched, next)}${next.endsWith("+") || matched.endsWith("+") ? "+" : ""}`; +} + +function currentRegion(text: string, start: RegExp, end: RegExp, update: (body: string) => string): string { + const match = start.exec(text); + if (!match) throw new Error(`Missing managed statistics region: ${start.source}`); + const after = match.index + match[0].length; + const boundary = text.slice(after).search(end); + const stop = boundary < 0 ? text.length : after + boundary; + return text.slice(0, match.index) + update(text.slice(match.index, stop)) + text.slice(stop); +} + +function syncCurrentRegions(files: Map, state: State): void { + // These regions describe current inventory; other prose and historical examples keep their own numbers. + const agents = files.get("AGENTS.md"); + const readme = files.get("README.md"); + if (!agents || !readme) throw new Error("Current statistics documents are missing."); + const number = "\\d+(?:[,.\\u00a0\\u202f ]\\d{3})*\\+?"; + const counters: Array<[string, string]> = [ + ["mcpTools", "MCP tools"], ["mcpResources", "MCP resources"], ["mcpPrompts", "MCP prompts"], + ["restEndpoints", "REST endpoints"], ["hooks", "hooks"], ["skills", "skills"], + ["functions", "iii functions"], ["tests", "tests"], ["coreTools", "essentials"], + ]; + files.set("AGENTS.md", currentRegion(agents, /^## Current Stats .*$/m, /^## /m, (body) => { + let next = body.replace(/^## Current Stats \([^)]*\)/m, `## Current Stats (v${state.version})`); + for (const [key, noun] of counters) next = next.replace(new RegExp(`${number}(?=\\s+${escapeRegex(noun)}\\b)`, "g"), (value) => currentCount(value, key, state)); + return next; + })); + files.set("README.md", currentRegion(readme, /^

.*$/m, /^

{ + const summary = new RegExp(`^(${number})( tools, )(${number})( resources, )(${number})( prompts, and )(${number})( skills\\.)$`, "m"); + if (!summary.test(body)) throw new Error("Missing managed MCP inventory summary."); + return body.replace(summary, (_all, tools: string, a: string, resources: string, b: string, prompts: string, c: string, skills: string, d: string) => + `${currentCount(tools, "mcpTools", state)}${a}${currentCount(resources, "mcpResources", state)}${b}${currentCount(prompts, "mcpPrompts", state)}${c}${currentCount(skills, "skills", state)}${d}`, + ).replace(new RegExp(`(?<=^### )${number}(?= Tools$)`, "gm"), (value) => currentCount(value, "mcpTools", state)) + .replace(new RegExp(`(?<=full )${number}(?=-tool surface)`, "g"), (value) => currentCount(value, "mcpTools", state)) + .replace(new RegExp(`(?<=falls back to a )${number}(?=-tool local set)`, "g"), (value) => currentCount(value, "fallbackTools", state)) + .replace(new RegExp(`(?<=see only )${number}(?= tools)`, "g"), (value) => currentCount(value, "fallbackTools", state)); + })); +} + function factRegex(fact: Fact, old: string): RegExp { const nouns = [...fact.nouns].sort((a, b) => b.length - a.length).map(escapeRegex).join("|"); const before = fact.before ? `(?<=${fact.before})` : ""; @@ -353,6 +423,28 @@ function main(): void { nextState.facts[fact.key] = [next]; } + syncCurrentRegions(files, nextState); + + // A docs-only edit can corrupt a generated badge while the saved facts stay current. + for (const fact of FACTS) { + const badge = fact.badge; + const next = nextState.facts[fact.key]?.[0]; + if (!badge || !next) continue; + for (const [path, text] of files) { + if (path.endsWith(badge)) { + files.set(path, syncBadge(text, next)); + } else if (text.includes(badge)) { + files.set(path, text.replace(/]*>/gi, (tag) => { + const src = tag.match(/\bsrc\s*=\s*(["'])(.*?)\1/i)?.[2]; + if (!src?.endsWith(badge)) return tag; + return tag.replace(/(\balt\s*=\s*)(["'])(.*?)\2/gi, (_match, prefix: string, quote: string, label: string) => + `${prefix}${quote}${syncBadgeNumber(label, next)}${quote}`, + ); + })); + } + } + } + const changed = [...files].filter(([p, t]) => original.get(p) !== t).map(([p]) => p); const stateChanged = JSON.stringify(nextState) !== JSON.stringify(state); diff --git a/src/cli/compose-control.ts b/src/cli/compose-control.ts index 6aea5df41c..999ad4d59b 100644 --- a/src/cli/compose-control.ts +++ b/src/cli/compose-control.ts @@ -214,7 +214,7 @@ async function composeCallWithClient(options: ComposeCallOptions, register: t let lastError: unknown; while (Date.now() < deadline) { try { - const result = await client.trigger({ + const result = await client.trigger<{ file: string }, T & { status?: string; error?: { code?: string; message?: string } }>({ function_id: options.functionId, payload: { file: options.file }, timeoutMs: options.timeoutMs ?? 30_000, diff --git a/src/cli/connect/dsh.ts b/src/cli/connect/dsh.ts index 9e8592dfa6..8fcfd93491 100644 --- a/src/cli/connect/dsh.ts +++ b/src/cli/connect/dsh.ts @@ -1,7 +1,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import * as p from "@clack/prompts"; -import { isMap, isSeq, parseDocument, type YAMLMap } from "yaml"; +import { isMap, isSeq, parseDocument, type Document, type YAMLMap } from "yaml"; import type { ConnectAdapter, ConnectOptions, ConnectResult } from "./types.js"; import { AGENTMEMORY_MCP_BLOCK, @@ -40,7 +40,7 @@ function hooksBlock(pluginPath: string): string { } function parsePatch(content: string) { - const doc = parseDocument(content); + const doc: Document = parseDocument(content); if (doc.contents === null) doc.contents = doc.createNode([]); if (doc.errors.length || !isSeq(doc.contents)) { throw new Error("Cannot update dsh cordis.patch.yml: expected a valid YAML sequence."); diff --git a/src/functions/capture.ts b/src/functions/capture.ts index 63561e48c2..d7430f9995 100644 --- a/src/functions/capture.ts +++ b/src/functions/capture.ts @@ -1,7 +1,5 @@ import { createHash, randomBytes } from "node:crypto"; import { readFileSync } from "node:fs"; -import { homedir } from "node:os"; -import { join } from "node:path"; import type { IIIClient } from "iii-sdk"; import type { CompressedObservation, HookPayload } from "../types.js"; import { KV, generateId } from "../state/schema.js"; diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.ts index d427a55fb6..4cda9db0d8 100644 --- a/src/functions/diagnostics.ts +++ b/src/functions/diagnostics.ts @@ -13,7 +13,6 @@ import type { Insight, Lease, Lesson, - Checkpoint, Crystal, ProceduralMemory, SemanticMemory, diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 088d46f438..f3453684d9 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -21,7 +21,6 @@ import type { Facet, Lesson, Insight, - ExportPagination, AccessLogExport, } from "../types.js"; import { importOrigin } from "../types.js"; diff --git a/src/functions/image-quota-cleanup.ts b/src/functions/image-quota-cleanup.ts index 12339bd658..ea4ebd80cb 100644 --- a/src/functions/image-quota-cleanup.ts +++ b/src/functions/image-quota-cleanup.ts @@ -1,5 +1,4 @@ import { TriggerAction, type IIIClient } from "iii-sdk"; -import { KV } from "../state/schema.js"; import { StateKV } from "../state/kv.js"; import { readdir, stat } from "node:fs/promises"; import { join } from "node:path"; diff --git a/src/functions/retention.ts b/src/functions/retention.ts index a40e5f4a78..4bcf70bf57 100644 --- a/src/functions/retention.ts +++ b/src/functions/retention.ts @@ -81,22 +81,6 @@ function computeReinforcementBoost( return boost * sigma; } -function computeRetention( - salience: number, - createdAt: string, - accessTimestamps: number[], - config: DecayConfig, -): number { - const deltaT = - (Date.now() - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24); - const temporalDecay = Math.exp(-config.lambda * deltaT); - const reinforcementBoost = computeReinforcementBoost( - accessTimestamps, - config.sigma, - ); - return Math.min(1, salience * temporalDecay + reinforcementBoost); -} - function computeSalience( memory: Memory | SemanticMemory, accessCount: number, diff --git a/src/functions/skill-extract.ts b/src/functions/skill-extract.ts index ad2977a87a..2779ec54c3 100644 --- a/src/functions/skill-extract.ts +++ b/src/functions/skill-extract.ts @@ -6,7 +6,7 @@ import type { Session, MemoryProvider, } from "../types.js"; -import { KV, generateId, fingerprintId } from "../state/schema.js"; +import { KV, fingerprintId } from "../state/schema.js"; import { StateKV, collectAll } from "../state/kv.js"; import { recordAudit } from "./audit.js"; import { logger } from "../logger.js"; diff --git a/src/functions/slots.ts b/src/functions/slots.ts index 0d3d0cee9c..e0cc24bdb7 100644 --- a/src/functions/slots.ts +++ b/src/functions/slots.ts @@ -146,7 +146,7 @@ function validateScope(raw: unknown): SlotScope | null { return null; } -function validateSizeLimit(raw: unknown): number | null | undefined { +function validateSizeLimit(raw: unknown): number | null { if (raw === undefined || raw === null) return DEFAULT_SIZE_LIMIT; if (typeof raw !== "number") return null; if (!Number.isInteger(raw) || raw < 1 || raw > 20000) return null; @@ -257,7 +257,7 @@ export function registerSlotsFunctions(sdk: IIIClient, kv: StateKV): void { const slot: MemorySlot = { label, content, - sizeLimit: sizeLimit as number, + sizeLimit, description, pinned, readOnly: false, @@ -314,26 +314,27 @@ export function registerSlotsFunctions(sdk: IIIClient, kv: StateKV): void { async (data: { label?: string; content?: string }) => { const label = validateLabel(data?.label); if (!label) return { success: false, error: "label required" }; - if (typeof data?.content !== "string") return { success: false, error: "content required (string)" }; + const content = data?.content; + if (typeof content !== "string") return { success: false, error: "content required (string)" }; return withKeyedLock(`slot:${label}`, async () => { const { slot, scope } = await readSlot(kv, label); if (!slot) return { success: false, error: "slot not found (use mem::slot-create first)" }; if (slot.readOnly) return { success: false, error: "slot is read-only" }; - if (data.content.length > slot.sizeLimit) { + if (content.length > slot.sizeLimit) { return { success: false, - error: `content exceeds sizeLimit (${data.content.length} > ${slot.sizeLimit})`, + error: `content exceeds sizeLimit (${content.length} > ${slot.sizeLimit})`, sizeLimit: slot.sizeLimit, }; } - const updated: MemorySlot = { ...slot, content: data.content, updatedAt: nowIso() }; + const updated: MemorySlot = { ...slot, content, updatedAt: nowIso() }; await kv.set(scopeKv(scope), label, updated); await recordAudit(kv, "slot_replace", "mem::slot-replace", [label], { scope, before: slot.content.length, - after: data.content.length, + after: content.length, }); - return { success: true, slot: updated, size: data.content.length }; + return { success: true, slot: updated, size: content.length }; }); }, ); diff --git a/src/functions/working-memory.ts b/src/functions/working-memory.ts index 6f606faa1e..5bbeddcc07 100644 --- a/src/functions/working-memory.ts +++ b/src/functions/working-memory.ts @@ -1,5 +1,5 @@ import type { IIIClient } from "iii-sdk"; -import type { Memory, CompressedObservation, ContextBlock } from "../types.js"; +import type { Memory } from "../types.js"; import { KV, generateId } from "../state/schema.js"; import { StateKV, collectAll } from "../state/kv.js"; import { recordAudit } from "./audit.js"; diff --git a/src/health/monitor.ts b/src/health/monitor.ts index 9f58882ada..b0071f6959 100644 --- a/src/health/monitor.ts +++ b/src/health/monitor.ts @@ -24,16 +24,9 @@ export function registerHealthMonitor( sdk: IIIClient, kv: StateKV, ): { stop: () => void } { - let connectionState = "connected"; let prevCpuUsage = process.cpuUsage(); let prevCpuTime = Date.now(); - if (typeof sdk.on === "function") { - sdk.on("connection_state", (state?: unknown) => { - connectionState = state as string; - }); - } - async function collectHealth(): Promise { const mem = process.memoryUsage(); const currentCpu = process.cpuUsage(); @@ -82,7 +75,7 @@ export function registerHealthMonitor( } const snapshot: HealthSnapshot = { - connectionState, + connectionState: sdk.getConnectionState(), liveEvents: getLiveEventsStats(), workers, memory: { diff --git a/src/providers/openai.ts b/src/providers/openai.ts index 929dc4c9c8..10af8fc59b 100644 --- a/src/providers/openai.ts +++ b/src/providers/openai.ts @@ -9,7 +9,6 @@ import { normalizeBaseUrl, } from "./_openai-shared.js"; -const DEFAULT_MODEL = "gpt-5.6-luna"; const DEFAULT_TIMEOUT_MS = 60_000; /** diff --git a/src/state/reranker.ts b/src/state/reranker.ts index efd842e559..eaf85f1116 100644 --- a/src/state/reranker.ts +++ b/src/state/reranker.ts @@ -28,7 +28,7 @@ async function loadScorer(): Promise { return_token_type_ids: true, }); const length = encoded.input_ids.length; - const boundary = encoded.token_type_ids.indexOf(1); + const boundary = encoded.token_type_ids?.indexOf(1) ?? -1; if (boundary < 2 || boundary >= length) throw new Error("Invalid BERT pair encoding"); // This model uses [CLS] query [SEP] document [SEP]. Transformers.js @@ -85,7 +85,7 @@ export async function rerank( return results; } scores.sort((a, b) => b.score - a.score || a.position - b.position); - return scores.map(({ result, score }, i) => ({ + return scores.map(({ result, score }, i) => ({ ...result, rerankScore: score, rerankPosition: i + 1, diff --git a/src/triggers/api.ts b/src/triggers/api.ts index 46e318b89d..83e2c342b7 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -34,7 +34,6 @@ import { } from "../functions/search.js"; import { LIST_PAGE_MAX, - decodeCursor, encodeCursor, matchesText, pageAfterCursor, @@ -671,7 +670,6 @@ export function registerApiTriggers( status_code: statusCode, body: { status, - service: "agentmemory", version: VERSION, health: health || null, functionMetrics, @@ -722,8 +720,8 @@ export function registerApiTriggers( }); sdk.registerFunction("api::observe", - async (req: HttpRequest): Promise => { - const body = (req.body ?? {}) as Record; + async (req: HttpRequest>): Promise => { + const body = req.body ?? {}; const hookType = asNonEmptyString(body.hookType); const sessionId = asNonEmptyString(body.sessionId); const project = asNonEmptyString(body.project); @@ -3422,7 +3420,7 @@ export function registerApiTriggers( }); sdk.registerFunction("api::routine-create", - async (req: HttpRequest): Promise => { + async (req: HttpRequest>): Promise => { const authErr = checkAuth(req, secret); if (authErr) return authErr; if (!req.body?.name || !req.body?.steps) { diff --git a/src/types.ts b/src/types.ts index d4061c1d58..4749833282 100644 --- a/src/types.ts +++ b/src/types.ts @@ -703,6 +703,7 @@ export interface AuditEntry { | "action_create" | "action_update" | "lease_acquire" + | "lease_renew" | "lease_release" | "routine_run" | "signal_send" diff --git a/test/ci-changes.test.ts b/test/ci-changes.test.ts new file mode 100644 index 0000000000..cab563a3d5 --- /dev/null +++ b/test/ci-changes.test.ts @@ -0,0 +1,84 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join, resolve } from "node:path"; +import { execFileSync, spawnSync } from "node:child_process"; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); + +function classify(paths: string[], eventName = "pull_request", options: { missingBase?: boolean; malformed?: boolean; deleted?: boolean; created?: boolean } = {}) { + const root = mkdtempSync(join(tmpdir(), "am-ci-changes-")); + roots.push(root); + const env = { PATH: process.env.PATH, HOME: root, USERPROFILE: root, LANG: "C.UTF-8", NO_COLOR: "1", GIT_CONFIG_NOSYSTEM: "1" }; + const git = (...args: string[]) => execFileSync("git", args, { cwd: root, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); + const put = (path: string, value: string) => { mkdirSync(dirname(join(root, path)), { recursive: true }); writeFileSync(join(root, path), value); }; + git("init"); + git("config", "user.name", "CI fixture"); + git("config", "user.email", "fixture@example.invalid"); + put("README.md", "original\n"); + for (const path of paths) put(path, "original\n"); + git("add", "--all"); + git("commit", "-m", "fixture base"); + const base = git("rev-parse", "HEAD"); + for (const path of paths) { + if (options.deleted) rmSync(join(root, path)); + else put(path, "changed\n"); + } + git("add", "--all"); + git("commit", "--allow-empty", "-m", "fixture change"); + const head = git("rev-parse", "HEAD"); + const effectiveBase = options.created ? "0".repeat(40) : options.missingBase ? "f".repeat(40) : base; + const event = eventName === "pull_request" ? { pull_request: { base: { sha: effectiveBase } } } : { before: effectiveBase }; + const eventPath = join(root, "event.json"); + const output = join(root, "output.txt"); + writeFileSync(eventPath, options.malformed ? "invalid json" : JSON.stringify(event)); + const result = spawnSync(process.execPath, [resolve("scripts/ci-changes.mjs")], { + cwd: root, encoding: "utf8", timeout: 10_000, + env: { ...env, GITHUB_EVENT_NAME: eventName, GITHUB_EVENT_PATH: eventPath, GITHUB_SHA: head, GITHUB_OUTPUT: output }, + }); + expect(result.error).toBeUndefined(); + expect(result.status).toBe(0); + const decision = JSON.parse(result.stdout) as { runTests: boolean; reason: string; paths?: string[] }; + expect(readFileSync(output, "utf8")).toBe(`run_tests=${decision.runTests}\n`); + return decision; +} + +describe("CI source and documentation routing", () => { + it.each(["README.md", "docs/guide.yml", "assets/logo.svg", "website/app.tsx", "nested/note.mdx", "deploy/native/README.md"])( + "keeps quality guards without running the test matrix for %s", (path) => { + expect(classify([path]).runTests).toBe(false); + }, + ); + it.each(["src/config.ts", "test/example.test.ts", "package.json", ".env.example", ".github/workflows/ci.yml"])( + "runs the matrix for %s", (path) => { + expect(classify([path]).runTests).toBe(true); + }, + ); + it("keeps source testing when documentation and source change together", () => { + expect(classify(["README.md", "src/config.ts"]).runTests).toBe(true); + }); + it("detects deleted source files", () => { + expect(classify(["src/deleted.ts"], "push", { deleted: true }).runTests).toBe(true); + }); + it("applies the same documentation policy to pushes", () => { + expect(classify(["README.md"], "push").runTests).toBe(false); + }); + it("handles newlines in Git paths without splitting one file into several", () => { + expect(classify(["docs/line\nbreak.md"]).paths).toEqual(["docs/line\nbreak.md"]); + }); + it("runs the full matrix on an explicit manual dispatch", () => { + expect(classify(["README.md"], "workflow_dispatch").runTests).toBe(true); + }); + it("runs source tests if the comparison commit is unavailable", () => { + expect(classify(["README.md"], "push", { missingBase: true }).runTests).toBe(true); + }); + it("runs source tests for a branch without a previous commit", () => { + expect(classify(["README.md"], "push", { created: true }).runTests).toBe(true); + }); + it("runs source tests if event data cannot be decoded", () => { + expect(classify(["README.md"], "pull_request", { malformed: true }).runTests).toBe(true); + }); +}); diff --git a/test/ci-source-contracts.test.ts b/test/ci-source-contracts.test.ts new file mode 100644 index 0000000000..110a7b8080 --- /dev/null +++ b/test/ci-source-contracts.test.ts @@ -0,0 +1,105 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { IIIClient } from "iii-sdk"; +import { registerHealthMonitor } from "../src/health/monitor.js"; +import { registerSlotsFunctions } from "../src/functions/slots.js"; +import { withKeyedLock } from "../src/state/keyed-mutex.js"; + +beforeEach(() => { + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval"] }); +}); +afterEach(() => { + vi.clearAllTimers(); + vi.useRealTimers(); +}); + +function memoryKV() { + const scopes = new Map>(); + return { + get: async (scope: string, key: string) => scopes.get(scope)?.get(key) ?? null, + set: async (scope: string, key: string, value: unknown) => { + if (!scopes.has(scope)) scopes.set(scope, new Map()); + scopes.get(scope)!.set(key, value); + return value; + }, + list: async (scope: string) => [...(scopes.get(scope)?.values() ?? [])], + }; +} + +async function healthFixture(initial: ReturnType) { + let state = initial; + let latest: unknown; + const sdk = { + getConnectionState: () => state, + trigger: async () => ({ workers: [] }), + }; + const kv = { + get: async () => null, + set: async (_scope: string, key: string, value: unknown) => { + if (key === "latest") latest = value; + return value; + }, + }; + const monitor = registerHealthMonitor(sdk as never, kv as never); + const snapshot = async () => { + for (let i = 0; i < 50 && latest === undefined; i++) { + await new Promise((resolve) => setImmediate(resolve)); + } + expect(latest).toBeDefined(); + return latest; + }; + return { + stop: monitor.stop, + snapshot, + change: (next: typeof state) => { state = next; latest = undefined; }, + }; +} + +describe("source contracts required by CI typechecking", () => { + it.each(["connected", "connecting", "disconnected", "reconnecting", "failed"] as const)( + "reports the SDK's actual %s connection state", async (state) => { + const f = await healthFixture(state); + try { + expect(await f.snapshot()).toMatchObject({ connectionState: state }); + } finally { + f.stop(); + } + }, + ); + + it("refreshes the SDK connection state on each health collection", async () => { + const f = await healthFixture("connected"); + try { + expect(await f.snapshot()).toMatchObject({ connectionState: "connected" }); + f.change("disconnected"); + await vi.advanceTimersByTimeAsync(30_000); + expect(await f.snapshot()).toMatchObject({ connectionState: "disconnected" }); + } finally { + f.stop(); + } + }); + + it("replaces a slot with the string validated before waiting for its lock", async () => { + const kv = memoryKV(); + const handlers = new Map) => Promise>(); + const sdk = { + registerFunction: (id: string, fn: (data: Record) => Promise) => handlers.set(id, fn), + }; + registerSlotsFunctions(sdk as never, kv as never); + expect(await handlers.get("mem::slot-create")!({ label: "ci_contract", content: "old", sizeLimit: 8 })) + .toMatchObject({ success: true }); + let release!: () => void; + let entered!: () => void; + const blocked = new Promise((resolve) => { release = resolve; }); + const started = new Promise((resolve) => { entered = resolve; }); + const hold = withKeyedLock("slot:ci_contract", async () => { entered(); await blocked; }); + await started; + const request = { label: "ci_contract", content: "valid" }; + const replacing = handlers.get("mem::slot-replace")!(request); + request.content = "changed after validation"; + release(); + await hold; + expect(await replacing).toMatchObject({ success: true, slot: { content: "valid" }, size: 5 }); + expect(await handlers.get("mem::slot-get")!({ label: "ci_contract" })) + .toMatchObject({ success: true, slot: { content: "valid" } }); + }); +}); diff --git a/test/env-example-bindings.test.ts b/test/env-example-bindings.test.ts new file mode 100644 index 0000000000..9674f80c78 --- /dev/null +++ b/test/env-example-bindings.test.ts @@ -0,0 +1,79 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { spawnSync } from "node:child_process"; + +type Case = { id: string; sources: Record; example: string; expected: number; missing?: string[] }; +const cases: Case[] = [ + { + id: "scoped literal keys remain distinct", + sources: { "fixture.ts": 'export function first() { const name = "UNDOCUMENTED_LEFT_SETTING"; return process.env[name]; }\nexport function second() { const name = "UNDOCUMENTED_RIGHT_SETTING"; return process.env[name]; }\n' }, + example: "", expected: 1, missing: ["UNDOCUMENTED_LEFT_SETTING", "UNDOCUMENTED_RIGHT_SETTING"], + }, + { + id: "documented scoped keys are not orphans", + sources: { "fixture.ts": 'export function first() { const name = "DOCUMENTED_LEFT_SETTING"; return process.env[name]; }\nexport function second() { const name = "DOCUMENTED_RIGHT_SETTING"; return process.env[name]; }\n' }, + example: "DOCUMENTED_LEFT_SETTING=\nDOCUMENTED_RIGHT_SETTING=\n", expected: 0, + }, + { + id: "an ordinary env property is not process environment", + sources: { "fixture.ts": 'const values = { env: { ORDINARY_OBJECT_LABEL: "label" } }; export const label = values.env.ORDINARY_OBJECT_LABEL;\n' }, + example: "", expected: 0, + }, + { + id: "a local reader alias retains its key argument", + sources: { "fixture.ts": 'function readConfig(name: string) { return process.env[name]; } const setting = readConfig; export const value = setting("UNDOCUMENTED_ALIAS_SETTING");\n' }, + example: "", expected: 1, missing: ["UNDOCUMENTED_ALIAS_SETTING"], + }, + { + id: "an ordinary object named env is not ambient environment", + sources: { "fixture.ts": 'const env = { ORDINARY_LOCAL_LABEL: "label" }; export const label = env.ORDINARY_LOCAL_LABEL;\n' }, + example: "", expected: 0, + }, + { + id: "an imported reader alias resolves across source files", + sources: { + "config.ts": "export function getEnvVar(name: string) { return process.env[name]; }\n", + "fixture.ts": 'import { getEnvVar as read } from "./config.js"; const setting = read; export const value = setting("UNDOCUMENTED_IMPORTED_SETTING");\n', + }, + example: "", expected: 1, missing: ["UNDOCUMENTED_IMPORTED_SETTING"], + }, + { + id: "a local process binding does not become the Node process", + sources: { "fixture.ts": 'const process = { env: { ORDINARY_PROCESS_LABEL: "label" } }; export const label = process.env.ORDINARY_PROCESS_LABEL;\n' }, + example: "", expected: 0, + }, + { + id: "a same-named ordinary function does not become a config reader", + sources: { "fixture.ts": 'function getEnvVar(name: string) { return { name }; } export const value = getEnvVar("ORDINARY_CALL_LABEL");\n' }, + example: "", expected: 0, + }, +]; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); + +describe("environment reader binding provenance", () => { + it.each(cases)("$id", ({ sources, example, expected, missing }) => { + const root = mkdtempSync(join(tmpdir(), "am-env-bindings-")); + roots.push(root); + mkdirSync(join(root, "src")); + mkdirSync(join(root, "scripts")); + for (const [name, text] of Object.entries(sources)) writeFileSync(join(root, "src", name), text); + writeFileSync(join(root, ".env.example"), example); + writeFileSync(join(root, "scripts/check-env-example.mjs"), readFileSync(resolve("scripts/check-env-example.mjs"))); + symlinkSync(resolve("node_modules"), join(root, "node_modules"), "dir"); + const result = spawnSync(process.execPath, [join(root, "scripts/check-env-example.mjs"), "--json"], { + cwd: root, encoding: "utf8", timeout: 15_000, + env: { PATH: process.env.PATH, HOME: root, USERPROFILE: root, LANG: "C.UTF-8", NO_COLOR: "1" }, + }); + expect(result.error).toBeUndefined(); + expect(result.status).toBe(expected); + const report = JSON.parse(result.stdout); + if (missing) expect(report.missing).toEqual(missing); + else expect(report).toMatchObject({ missing: [], orphan: [] }); + }); +}); diff --git a/test/env-example-check.test.ts b/test/env-example-check.test.ts new file mode 100644 index 0000000000..44625ffd04 --- /dev/null +++ b/test/env-example-check.test.ts @@ -0,0 +1,66 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { spawnSync } from "node:child_process"; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); + +function check(source: string, example = "", spaces = false) { + const root = mkdtempSync(join(tmpdir(), spaces ? "am env guard " : "am-env-guard-")); + roots.push(root); + mkdirSync(join(root, "src")); + mkdirSync(join(root, "scripts")); + writeFileSync(join(root, "src/fixture.ts"), source); + writeFileSync(join(root, ".env.example"), example); + writeFileSync(join(root, "scripts/check-env-example.mjs"), readFileSync(resolve("scripts/check-env-example.mjs"))); + symlinkSync(resolve("node_modules"), join(root, "node_modules"), "dir"); + const result = spawnSync(process.execPath, [join(root, "scripts/check-env-example.mjs")], { + cwd: root, encoding: "utf8", timeout: 15_000, + env: { PATH: process.env.PATH, HOME: root, USERPROFILE: root, LANG: "C.UTF-8", NO_COLOR: "1" }, + }); + expect(result.error).toBeUndefined(); + return { code: result.status, output: result.stdout + result.stderr }; +} + +describe("environment example coverage guard", () => { + it.each([ + 'const value = process.env["UNDOCUMENTED_GUARD_SETTING"];', + "const value = process.env['UNDOCUMENTED_GUARD_SETTING'];", + "const value = process.env.UNDOCUMENTED_GUARD_SETTING;", + 'const value = getEnvVar("UNDOCUMENTED_GUARD_SETTING");', + "const value = getEnvVar('UNDOCUMENTED_GUARD_SETTING');", + "const env = process.env; const value = env.UNDOCUMENTED_GUARD_SETTING;", + "const { UNDOCUMENTED_GUARD_SETTING: value } = process.env;", + 'function envValue(key: string) { return process.env[key]; } const value = envValue("UNDOCUMENTED_GUARD_SETTING");', + ])("rejects an undocumented literal configuration reader: %s", (source) => { + const result = check(source); + expect(result.code).toBe(1); + expect(result.output).toContain("UNDOCUMENTED_GUARD_SETTING"); + }); + + it("accepts a documented configuration setting regardless of access notation", () => { + const result = check("const value = process.env.DOCUMENTED_GUARD_SETTING;", "DOCUMENTED_GUARD_SETTING=\n"); + expect(result.code).toBe(0); + }); + + it("does not turn unrelated strings and comments into configuration readers", () => { + const result = check('const labels = ["NOT_AN_ENVIRONMENT_SETTING"]; // process.env["COMMENT_ONLY_SETTING"]\n'); + expect(result.code).toBe(0); + }); + + it("keeps an explicit exception for inherited operating-system variables", () => { + expect(check('const home = process.env["HOME"];').code).toBe(0); + }); + + it("keeps documented telemetry configuration consumed by the pinned engine SDK", () => { + expect(check("", "III_TELEMETRY_ENABLED=false\n").code).toBe(0); + }); + + it("resolves an ordinary checkout path containing spaces", () => { + expect(check('const value = process.env["DOCUMENTED_GUARD_SETTING"];', "DOCUMENTED_GUARD_SETTING=\n", true).code).toBe(0); + }); +}); diff --git a/test/env-example-process-imports.test.ts b/test/env-example-process-imports.test.ts new file mode 100644 index 0000000000..fb47e5283e --- /dev/null +++ b/test/env-example-process-imports.test.ts @@ -0,0 +1,40 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { spawnSync } from "node:child_process"; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); +const imports = [ + ['import proc from "node:process";', "proc.env"], + ['import * as proc from "node:process";', "proc.env"], + ['import { default as proc } from "node:process";', "proc.env"], + ['import { env as environment } from "node:process";', "environment"], + ['import proc from "process";', "proc.env"], + ['import { env as environment } from "process";', "environment"], +]; + +describe("Node process import provenance", () => { + it.each(imports)("checks the literal key through %s", (declaration, receiver) => { + for (const documented of [false, true]) { + const root = mkdtempSync(join(tmpdir(), "am-env-process-import-")); + roots.push(root); + mkdirSync(join(root, "src")); + mkdirSync(join(root, "scripts")); + writeFileSync(join(root, "src/fixture.ts"), `${declaration}\nexport const value = ${receiver}.PROCESS_IMPORT_SETTING;\n`); + writeFileSync(join(root, ".env.example"), documented ? "PROCESS_IMPORT_SETTING=\n" : ""); + writeFileSync(join(root, "scripts/check-env-example.mjs"), readFileSync(resolve("scripts/check-env-example.mjs"))); + symlinkSync(resolve("node_modules"), join(root, "node_modules"), "dir"); + const result = spawnSync(process.execPath, [join(root, "scripts/check-env-example.mjs"), "--json"], { + cwd: root, encoding: "utf8", timeout: 15_000, + env: { PATH: process.env.PATH, HOME: root, USERPROFILE: root, LANG: "C.UTF-8", NO_COLOR: "1" }, + }); + expect(result.error).toBeUndefined(); + expect(result.status).toBe(documented ? 0 : 1); + expect(JSON.parse(result.stdout)).toMatchObject({ missing: documented ? [] : ["PROCESS_IMPORT_SETTING"], orphan: [] }); + } + }); +}); diff --git a/test/health-monitor-cpu.test.ts b/test/health-monitor-cpu.test.ts index 1fbdb3c2ed..105c74a578 100644 --- a/test/health-monitor-cpu.test.ts +++ b/test/health-monitor-cpu.test.ts @@ -59,6 +59,7 @@ function mockKV() { function mockSdk() { return { + getConnectionState: () => "connected" as const, trigger: async () => ({ workers: [] }), }; } From b17b8579bfb7865aa4669da87cab2b037ff93b2e Mon Sep 17 00:00:00 2001 From: zack-dev-cm <112114097+zack-dev-cm@users.noreply.github.com> Date: Fri, 13 Nov 2026 11:29:13 +0400 Subject: [PATCH 2/3] fix(ci): validate API counts and clarify search diagnostics Signed-off-by: zack-dev-cm <112114097+zack-dev-cm@users.noreply.github.com> --- .env.example | 2 +- scripts/docs-sync.ts | 10 +++++-- test/docs-api-drift.test.ts | 52 +++++++++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 3 deletions(-) create mode 100644 test/docs-api-drift.test.ts diff --git a/.env.example b/.env.example index 03bd1dcee6..1080efa038 100644 --- a/.env.example +++ b/.env.example @@ -279,7 +279,7 @@ # Set to 1 to disable the managed Compose restart policy. #AGENTMEMORY_DISABLE_COMPOSE_RESTART= -# Window for session follow-up scheduling, in seconds. +# Smart-search follow-up diagnostic window for repeated searches with disjoint results, in seconds (default: 30). #AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS= # Maximum total managed image-store size, in bytes. diff --git a/scripts/docs-sync.ts b/scripts/docs-sync.ts index 4043abd859..2a09b6e41f 100644 --- a/scripts/docs-sync.ts +++ b/scripts/docs-sync.ts @@ -285,7 +285,7 @@ function syncCurrentRegions(files: Map, state: State): void { for (const [key, noun] of counters) next = next.replace(new RegExp(`${number}(?=\\s+${escapeRegex(noun)}\\b)`, "g"), (value) => currentCount(value, key, state)); return next; })); - files.set("README.md", currentRegion(readme, /^

.*$/m, /^

{ + let currentReadme = currentRegion(readme, /^

.*$/m, /^

{ const summary = new RegExp(`^(${number})( tools, )(${number})( resources, )(${number})( prompts, and )(${number})( skills\\.)$`, "m"); if (!summary.test(body)) throw new Error("Missing managed MCP inventory summary."); return body.replace(summary, (_all, tools: string, a: string, resources: string, b: string, prompts: string, c: string, skills: string, d: string) => @@ -294,7 +294,13 @@ function syncCurrentRegions(files: Map, state: State): void { .replace(new RegExp(`(?<=full )${number}(?=-tool surface)`, "g"), (value) => currentCount(value, "mcpTools", state)) .replace(new RegExp(`(?<=falls back to a )${number}(?=-tool local set)`, "g"), (value) => currentCount(value, "fallbackTools", state)) .replace(new RegExp(`(?<=see only )${number}(?= tools)`, "g"), (value) => currentCount(value, "fallbackTools", state)); - })); + }); + currentReadme = currentRegion(currentReadme, /^

.*$/m, /^

{ + const summary = new RegExp(`^${number}(?= endpoints on port )`, "m"); + if (!summary.test(body)) throw new Error("Missing managed API inventory summary."); + return body.replace(summary, (value) => currentCount(value, "restEndpoints", state)); + }); + files.set("README.md", currentReadme); } function factRegex(fact: Fact, old: string): RegExp { diff --git a/test/docs-api-drift.test.ts b/test/docs-api-drift.test.ts new file mode 100644 index 0000000000..f4afda2806 --- /dev/null +++ b/test/docs-api-drift.test.ts @@ -0,0 +1,52 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { cpSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { expect, it } from "vitest"; + +const root = fileURLToPath(new URL("../", import.meta.url)); + +it("rejects and repairs current API-count drift without changing historical prose", () => { + const fixture = mkdtempSync(join(tmpdir(), "am-docs-api-")); + try { + const archive = execFileSync("git", ["archive", "--format=tar", "HEAD"], { cwd: root, maxBuffer: 128 * 1024 * 1024 }); + execFileSync("tar", ["-xf", "-", "-C", fixture], { input: archive }); + // Before a commit, test the same working files as the developer's local run. + const changed = execFileSync("git", ["ls-files", "--modified", "--others", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8" }); + for (const path of changed.split("\0").filter(Boolean)) cpSync(join(root, path), join(fixture, path), { recursive: true }); + cpSync(join(root, "dist"), join(fixture, "dist"), { recursive: true }); + symlinkSync(join(root, "node_modules"), join(fixture, "node_modules"), "junction"); + execFileSync("git", ["init", "--quiet"], { cwd: fixture }); + const env = { + PATH: process.env.PATH, HOME: fixture, USERPROFILE: fixture, LANG: "C.UTF-8", + CI: "1", NO_COLOR: "1", III_TELEMETRY_ENABLED: "false", + NODE_OPTIONS: "--max-old-space-size=2048", + }; + const run = (check: boolean) => { + const result = spawnSync(process.execPath, [join(fixture, "node_modules/tsx/dist/cli.mjs"), join(fixture, "scripts/docs-sync.ts"), ...(check ? ["--check"] : [])], { + cwd: fixture, env, encoding: "utf8", timeout: 120_000, maxBuffer: 4 * 1024 * 1024, + }); + expect(result.error, result.stderr).toBeUndefined(); + return result; + }; + const readme = join(fixture, "README.md"); + const original = readFileSync(readme, "utf8"); + const historical = "Historical example: 999 endpoints on port 1234.\n\n"; + writeFileSync(readme, historical + original); + expect(run(true).status).toBe(0); + const summary = /^(\d+(?:[,.\u00a0\u202f ]\d{3})*) endpoints on port /m.exec(original); + const count = summary?.[1]; + expect(count).toBeDefined(); + if (!summary || !count) throw new Error("Current API inventory summary is missing"); + const incorrect = String(Number(count.replace(/\D/g, "")) + 1); + writeFileSync(readme, historical + original.replace(summary[0], `${incorrect} endpoints on port `)); + const rejected = run(true); + expect(rejected.status).toBe(1); + expect(rejected.stderr).toContain("would update README.md"); + expect(run(false).status).toBe(0); + expect(readFileSync(readme, "utf8")).toBe(historical + original); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } +}, 400_000); From 6aba073a8335167ef1ecd6320c3391abfd9de56e Mon Sep 17 00:00:00 2001 From: zack-dev-cm <112114097+zack-dev-cm@users.noreply.github.com> Date: Fri, 13 Nov 2026 12:42:25 +0400 Subject: [PATCH 3/3] fix: address CI guard review regressions Signed-off-by: zack-dev-cm <112114097+zack-dev-cm@users.noreply.github.com> --- AGENTS.md | 2 +- scripts/check-env-example.mjs | 4 +- scripts/docs-sync.ts | 2 +- test/docs-api-drift.test.ts | 15 ++++--- test/env-example-computed-access.test.ts | 52 ++++++++++++++++++++++++ test/git-checkout-fixture.test.ts | 45 ++++++++++++++++++++ test/helpers/git-checkout-fixture.ts | 17 ++++++++ 7 files changed, 128 insertions(+), 9 deletions(-) create mode 100644 test/env-example-computed-access.test.ts create mode 100644 test/git-checkout-fixture.test.ts create mode 100644 test/helpers/git-checkout-fixture.ts diff --git a/AGENTS.md b/AGENTS.md index eb4ff24f9d..27c9e90eaf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -113,5 +113,5 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). - 147 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 17 skills -- 323+ iii functions +- 323 iii functions - 4,900+ tests diff --git a/scripts/check-env-example.mjs b/scripts/check-env-example.mjs index 886c2981a6..0eb19ce8c7 100644 --- a/scripts/check-env-example.mjs +++ b/scripts/check-env-example.mjs @@ -107,6 +107,7 @@ function environment(node, seen = new Set()) { if (!node) return false; if (builtinImport(node, "env")) return true; if (ts.isPropertyAccessExpression(node) && node.name.text === "env" && processObject(node.expression)) return true; + if (ts.isElementAccessExpression(node) && constant(node.argumentExpression) === "env" && processObject(node.expression)) return true; if (ts.isCallExpression(node) && environmentReturns.has(target(node.expression))) return true; if (ts.isBinaryExpression(node) && [ts.SyntaxKind.QuestionQuestionToken, ts.SyntaxKind.BarBarToken].includes(node.operatorToken.kind)) return environment(node.left, new Set(seen)) || environment(node.right, new Set(seen)); if (ts.isObjectLiteralExpression(node)) return node.properties.some((property) => ts.isSpreadAssignment(property) && environment(property.expression, new Set(seen))); @@ -178,7 +179,8 @@ for (const source of sources) visit(source, (node) => { if (key) record(ts.isPropertyAccessExpression(node) ? node.name.text : constant(key), node); if (ts.isCallExpression(node)) for (const index of positions(node.expression)) record(constant(node.arguments[index]), node); if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && environment(node.initializer)) for (const binding of node.name.elements) { - if (!binding.dotDotDotToken) record((binding.propertyName ?? binding.name).text, binding); + const name = binding.propertyName ?? binding.name; + if (!binding.dotDotDotToken) record(ts.isComputedPropertyName(name) ? constant(name.expression) : name.text, binding); } }); const documented = new Set(); diff --git a/scripts/docs-sync.ts b/scripts/docs-sync.ts index 2a09b6e41f..73b9fbbbd0 100644 --- a/scripts/docs-sync.ts +++ b/scripts/docs-sync.ts @@ -257,7 +257,7 @@ function syncBadge(text: string, next: string): string { function currentCount(matched: string, key: string, state: State): string { const next = state.facts[key]?.[0]; if (!next) throw new Error(`Could not compute current ${key}.`); - return `${formatLike(matched, next)}${next.endsWith("+") || matched.endsWith("+") ? "+" : ""}`; + return `${formatLike(matched, next)}${next.endsWith("+") ? "+" : ""}`; } function currentRegion(text: string, start: RegExp, end: RegExp, update: (body: string) => string): string { diff --git a/test/docs-api-drift.test.ts b/test/docs-api-drift.test.ts index f4afda2806..cd66a09fed 100644 --- a/test/docs-api-drift.test.ts +++ b/test/docs-api-drift.test.ts @@ -4,17 +4,14 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { expect, it } from "vitest"; +import { copyGitCheckout } from "./helpers/git-checkout-fixture.js"; const root = fileURLToPath(new URL("../", import.meta.url)); it("rejects and repairs current API-count drift without changing historical prose", () => { const fixture = mkdtempSync(join(tmpdir(), "am-docs-api-")); try { - const archive = execFileSync("git", ["archive", "--format=tar", "HEAD"], { cwd: root, maxBuffer: 128 * 1024 * 1024 }); - execFileSync("tar", ["-xf", "-", "-C", fixture], { input: archive }); - // Before a commit, test the same working files as the developer's local run. - const changed = execFileSync("git", ["ls-files", "--modified", "--others", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8" }); - for (const path of changed.split("\0").filter(Boolean)) cpSync(join(root, path), join(fixture, path), { recursive: true }); + copyGitCheckout(root, fixture); cpSync(join(root, "dist"), join(fixture, "dist"), { recursive: true }); symlinkSync(join(root, "node_modules"), join(fixture, "node_modules"), "junction"); execFileSync("git", ["init", "--quiet"], { cwd: fixture }); @@ -46,7 +43,13 @@ it("rejects and repairs current API-count drift without changing historical pros expect(rejected.stderr).toContain("would update README.md"); expect(run(false).status).toBe(0); expect(readFileSync(readme, "utf8")).toBe(historical + original); + writeFileSync(readme, historical + original.replace(summary[0], `${count}+ endpoints on port `)); + const inexact = run(true); + expect(inexact.status).toBe(1); + expect(inexact.stderr).toContain("would update README.md"); + expect(run(false).status).toBe(0); + expect(readFileSync(readme, "utf8")).toBe(historical + original); } finally { rmSync(fixture, { recursive: true, force: true }); } -}, 400_000); +}, 640_000); diff --git a/test/env-example-computed-access.test.ts b/test/env-example-computed-access.test.ts new file mode 100644 index 0000000000..282b8fc62d --- /dev/null +++ b/test/env-example-computed-access.test.ts @@ -0,0 +1,52 @@ +import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { afterEach, expect, it } from "vitest"; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); +function checkForms(key: string, sources: string[], reader = true) { + const observed = [], expected = []; + for (const source of sources) for (const documented of [false, true]) { + const root = mkdtempSync(join(tmpdir(), "am-env-computed-")); + roots.push(root); + mkdirSync(join(root, "src")); mkdirSync(join(root, "scripts")); + writeFileSync(join(root, "src/fixture.ts"), source); + writeFileSync(join(root, ".env.example"), documented ? `${key}=\n` : ""); + writeFileSync(join(root, "scripts/check-env-example.mjs"), readFileSync(resolve("scripts/check-env-example.mjs"))); + symlinkSync(resolve("node_modules"), join(root, "node_modules"), "dir"); + const result = spawnSync(process.execPath, [join(root, "scripts/check-env-example.mjs"), "--json"], { + cwd: root, encoding: "utf8", timeout: 15_000, + env: { PATH: process.env.PATH, HOME: root, USERPROFILE: root, LANG: "C.UTF-8", NO_COLOR: "1" }, + }); + expect(result.error).toBeUndefined(); + const report: { missing: string[]; orphan: string[] } = JSON.parse(result.stdout); + observed.push({ source, documented, status: result.status, missing: report.missing, orphan: report.orphan }); + const missing = !documented && reader ? [key] : []; + const orphan = documented && !reader ? [key] : []; + expected.push({ source, documented, status: missing.length || orphan.length ? 1 : 0, missing, orphan }); + } + expect(observed).toEqual(expected); +} +it("recognizes bracketed process environment receivers and their static keys", () => { + checkForms("BRACKET_SETTING", [ + 'export const value = process["env"]["BRACKET_SETTING"];', + 'export const value = process["env"].BRACKET_SETTING;', + 'const name = "env"; export const value = process[name].BRACKET_SETTING;', + ]); +}, 120_000); +it("resolves literal and constant computed destructuring keys", () => { + checkForms("COMPUTED_SETTING", [ + 'const { ["COMPUTED_SETTING"]: value } = process.env; void value;', + 'const key = "COMPUTED_SETTING"; const { [key]: value } = process.env; void value;', + ]); +}, 120_000); +it("keeps ordinary bracketed objects and shadowed process parameters out of environment readers", () => { + checkForms("FAKE_SETTING", [ + 'const ordinary = { env: { FAKE_SETTING: "local" } }; export const value = ordinary["env"].FAKE_SETTING;', + 'function local(process: { env: Record }) { return process["env"]["FAKE_SETTING"]; } export const value = local({ env: { FAKE_SETTING: "local" } });', + ], false); +}, 120_000); diff --git a/test/git-checkout-fixture.test.ts b/test/git-checkout-fixture.test.ts new file mode 100644 index 0000000000..2c5c1494d2 --- /dev/null +++ b/test/git-checkout-fixture.test.ts @@ -0,0 +1,45 @@ +import { execFileSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, expect, it } from "vitest"; +import { copyGitCheckout } from "./helpers/git-checkout-fixture.js"; + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); +function repository() { + const root = mkdtempSync(join(tmpdir(), "am-checkout-fixture-")); + roots.push(root); + const source = join(root, "source"), destination = join(root, "copy"); + mkdirSync(source); mkdirSync(destination); + const git = (...args: string[]) => execFileSync("git", args, { cwd: source, stdio: "pipe" }); + git("init", "--quiet"); + for (const name of ["tracked.txt", "worktree.txt", "deleted.txt", "staged-deleted.txt", "rename-old.txt"]) writeFileSync(join(source, name), "HEAD\n"); + git("add", "."); + git("-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "--quiet", "-m", "fixture"); + return { source, destination, git }; +} +it("copies staged modifications and new files together with current worktree contents", () => { + const { source, destination, git } = repository(); + writeFileSync(join(source, "tracked.txt"), "INDEX\n"); + writeFileSync(join(source, "staged new.txt"), "NEW\n"); + git("add", "tracked.txt", "staged new.txt"); + writeFileSync(join(source, "worktree.txt"), "WORKTREE\n"); + writeFileSync(join(source, "untracked.txt"), "UNTRACKED\n"); + copyGitCheckout(source, destination); + expect(readFileSync(join(destination, "tracked.txt"), "utf8")).toBe("INDEX\n"); + expect(readFileSync(join(destination, "staged new.txt"), "utf8")).toBe("NEW\n"); + expect(readFileSync(join(destination, "worktree.txt"), "utf8")).toBe("WORKTREE\n"); + expect(readFileSync(join(destination, "untracked.txt"), "utf8")).toBe("UNTRACKED\n"); +}); +it("removes staged and unstaged deletions and preserves a staged rename", () => { + const { source, destination, git } = repository(); + rmSync(join(source, "deleted.txt")); + git("rm", "--quiet", "staged-deleted.txt"); + git("mv", "rename-old.txt", "renamed.txt"); + expect(() => copyGitCheckout(source, destination)).not.toThrow(); + for (const name of ["deleted.txt", "staged-deleted.txt", "rename-old.txt"]) expect(existsSync(join(destination, name))).toBe(false); + expect(readFileSync(join(destination, "renamed.txt"), "utf8")).toBe("HEAD\n"); +}); diff --git a/test/helpers/git-checkout-fixture.ts b/test/helpers/git-checkout-fixture.ts new file mode 100644 index 0000000000..faf2563ab5 --- /dev/null +++ b/test/helpers/git-checkout-fixture.ts @@ -0,0 +1,17 @@ +import { execFileSync } from "node:child_process"; +import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs"; +import { dirname, join } from "node:path"; + +export function copyGitCheckout(source: string, destination: string): void { + const archive = execFileSync("git", ["archive", "--format=tar", "HEAD"], { cwd: source, maxBuffer: 128 * 1024 * 1024 }); + execFileSync("tar", ["-xf", "-", "-C", destination], { input: archive }); + const changed = execFileSync("git", ["diff", "--name-only", "--no-renames", "-z", "HEAD", "--"], { cwd: source, encoding: "utf8" }); + const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: source, encoding: "utf8" }); + for (const path of new Set((changed + untracked).split("\0").filter(Boolean))) { + const current = join(source, path), target = join(destination, path); + if (existsSync(current)) { + mkdirSync(dirname(target), { recursive: true }); + cpSync(current, target, { recursive: true }); + } else rmSync(target, { recursive: true, force: true }); + } +}