* test(graphify): TDD-red design contract for #3170 commit-staleness signal Captures the proposed extension to graphifyStatus() as 8 failing assertions across 3 groups (git-aware, non-git, back-compat). Suite is describe.skip()'d so npm test stays green on the branch — removing .skip is the green-light moment when the enhancement is approved and implementation lands. Verified against safishamsi/graphify v0.7.0 release notes: the field on graph.json is built_at_commit (full git HEAD), not commit_hash as originally guessed in #3170. Tests assert against the verified name. Design highlights captured in the file's docstring: - Tri-state commit_stale (true/false/null) — null means "we don't know" (pre-v0.7 graph or no git), distinct from false ("known fresh") - Argument-injection fence /^[0-9a-f]{4,40}$/i validates built_at_commit before it reaches `git` as an argv element - Existing graphifyStatus() fields (node_count, edge_count, stale, age_hours, etc.) are unchanged — back-compat fenced Per the issue's enhancement template: no PR will be opened until the issue is labeled `approved-enhancement`. Refs #3170 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(graphify): surface commit-based staleness from graphify v0.7+ built_at_commit Closes #3170 graphify v0.7+ embeds built_at_commit (full git HEAD) into graph.json at write time. GSD's existing graphifyStatus() ignored it; staleness was mtime-only, which is a poor proxy for "does this graph reflect the current code." A CI-built graph rebuilt minutes ago against an old checkout reads as FRESH on mtime but is materially stale. graphifyStatus() now returns four additional fields on the success path: built_at_commit short hash from graph.built_at_commit, or null current_commit short hash of git HEAD, or null when no git commits_behind git rev-list --count <built>..HEAD, or null commit_stale true | false | null Tri-state on commit_stale is load-bearing. null means "we don't know" (pre-v0.7 graph, non-git cwd, unreachable commit) — semantically distinct from false ("known fresh"). Agents reading null should fall back to mtime; reading false can confidently skip a rebuild. Security: built_at_commit is on-disk and user-influenceable. Without validation, a hostile value (e.g. "--upload-pack=evil") would reach git as an argv element and be interpreted as an option. The /^[0-9a-f]{4,40}$/i fence rejects anything else as absent. spawnSync's array args (no shell) is defense in depth, not the boundary. Skill (commands/gsd/graphify.md) Step 2b renders one conditional line: Source commit: abc1234 (5 commits behind HEAD) Source commit: abc1234 (current) Source commit: abc1234 (freshness unknown) Pre-v0.7 graphs omit the line entirely — no confusing "Source commit: unknown" rendered. Also documents `graphify hook install` in docs/CONFIGURATION.md for multi-dev teams who would otherwise hit graph.json merge conflicts on parallel rebuilds (sub-enhancement 2 from #3170). TDD red→green: tests/enh-3170-graphify-commit-staleness.test.cjs (8 assertions across git-aware, non-git, back-compat) was committed describe.skip()'d in c567f23d when the issue was filed; this commit removes .skip and lands the implementation that makes them green. Full suite 7503/7503 passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const childProcess = require('child_process');
|
||||
const { atomicWriteFileSync } = require('./core.cjs');
|
||||
const { atomicWriteFileSync, execGit } = require('./core.cjs');
|
||||
|
||||
// ─── Config Gate ─────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -358,9 +358,44 @@ function graphifyQuery(cwd, term, options = {}) {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Strict 4-40 hex fence for graph.built_at_commit values (#3170). Anything
|
||||
* else (dashed, prose, empty) is treated as absent so a hostile graph.json
|
||||
* cannot smuggle a `--upload-pack=…` option into a `git` argv.
|
||||
*/
|
||||
const COMMIT_HASH_RE = /^[0-9a-f]{4,40}$/i;
|
||||
|
||||
/**
|
||||
* Read git HEAD for the project at `cwd`. Returns the full commit hash on
|
||||
* success, or null when cwd is not a git repo / `git` is not on PATH.
|
||||
*/
|
||||
function readGitHead(cwd) {
|
||||
const r = execGit(cwd, ['rev-parse', 'HEAD']);
|
||||
if (r.exitCode !== 0) return null;
|
||||
return r.stdout.trim() || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Count commits between `from` and `to` (exclusive..inclusive, like
|
||||
* `git rev-list --count A..B`). Returns null when either ref is unreachable
|
||||
* or the cwd is not a git repo.
|
||||
*/
|
||||
function countCommitsBetween(cwd, from, to) {
|
||||
const r = execGit(cwd, ['rev-list', '--count', `${from}..${to}`]);
|
||||
if (r.exitCode !== 0) return null;
|
||||
const n = parseInt(r.stdout.trim(), 10);
|
||||
return Number.isFinite(n) ? n : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return status information about the knowledge graph (STAT-01, STAT-02).
|
||||
*
|
||||
* Surfaces the graphify v0.7+ commit-staleness signal as four optional
|
||||
* fields when graph.built_at_commit is present and validly formatted
|
||||
* (#3170). Tri-state on commit_stale: null means "we don't know" (pre-v0.7
|
||||
* graph, no git, or unreachable commit), distinct from false ("known
|
||||
* fresh").
|
||||
*
|
||||
* @param {string} cwd - Working directory
|
||||
* @returns {object}
|
||||
*/
|
||||
@@ -382,6 +417,17 @@ function graphifyStatus(cwd) {
|
||||
const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
|
||||
const age = Date.now() - stat.mtimeMs;
|
||||
|
||||
// Commit-staleness signal (#3170). Validate before passing to git.
|
||||
const rawBuilt = (graph.built_at_commit || '').toString().trim();
|
||||
const builtAt = COMMIT_HASH_RE.test(rawBuilt) ? rawBuilt : null;
|
||||
const head = readGitHead(cwd);
|
||||
let commitsBehind = null;
|
||||
let commitStale = null;
|
||||
if (builtAt && head) {
|
||||
commitsBehind = countCommitsBetween(cwd, builtAt, head);
|
||||
if (commitsBehind !== null) commitStale = commitsBehind > 0;
|
||||
}
|
||||
|
||||
return {
|
||||
exists: true,
|
||||
last_build: stat.mtime.toISOString(),
|
||||
@@ -390,6 +436,10 @@ function graphifyStatus(cwd) {
|
||||
hyperedge_count: (graph.hyperedges || []).length,
|
||||
stale: age > STALE_MS,
|
||||
age_hours: Math.round(age / (60 * 60 * 1000)),
|
||||
built_at_commit: builtAt ? builtAt.slice(0, 7) : null,
|
||||
current_commit: head ? head.slice(0, 7) : null,
|
||||
commits_behind: commitsBehind,
|
||||
commit_stale: commitStale,
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user