scrumrun 1.5.2 → 2.0.0

package/lib/code-intel/scanner.js

@@ -0,0 +1,126 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { JavaScriptAdapter } = require("./javascript");
+
+const EXCLUDED = new Set([".git", ".scrumrun", "node_modules", "vendor", "dist", "build", "coverage", ".next", ".nuxt"]);
+const TEST_FILE = /(?:^|\/)(?:__tests__\/.*|[^/]*(?:\.test|\.spec)\.[^/]+)$/i;
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function currentCommit(projectRoot) {
+  const gitDir = path.join(projectRoot, ".git");
+  const headFile = path.join(gitDir, "HEAD");
+  if (!fs.existsSync(headFile)) return null;
+  const head = fs.readFileSync(headFile, "utf8").trim();
+  if (/^[a-f0-9]{40,64}$/i.test(head)) return head;
+  const ref = (head.match(/^ref:\s+(.+)$/) || [])[1];
+  if (!ref || ref.includes("..")) return null;
+  const loose = path.join(gitDir, ref);
+  if (fs.existsSync(loose)) return fs.readFileSync(loose, "utf8").trim() || null;
+  const packed = path.join(gitDir, "packed-refs");
+  if (!fs.existsSync(packed)) return null;
+  const match = fs.readFileSync(packed, "utf8").match(new RegExp(`^([a-f0-9]{40,64})\\s+${ref.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m"));
+  return match ? match[1] : null;
+}
+
+function sourceFiles(projectRoot, adapters, { maxFiles = 2000, maxFileBytes = 1024 * 1024 } = {}) {
+  const files = [];
+  const warnings = [];
+  function walk(directory) {
+    if (files.length >= maxFiles) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (files.length >= maxFiles) break;
+      if (entry.isSymbolicLink()) {
+        warnings.push(`Skipped symbolic link: ${posix(path.relative(projectRoot, path.join(directory, entry.name)))}`);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!EXCLUDED.has(entry.name)) walk(path.join(directory, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const file = path.join(directory, entry.name);
+      const adapter = adapters.find((candidate) => candidate.supports(file));
+      if (!adapter) continue;
+      const size = fs.statSync(file).size;
+      if (size > maxFileBytes) {
+        warnings.push(`Skipped oversized source: ${posix(path.relative(projectRoot, file))}`);
+        continue;
+      }
+      files.push({ file, relative: path.relative(projectRoot, file), adapter });
+    }
+  }
+  walk(projectRoot);
+  if (files.length >= maxFiles) warnings.push(`Source scan reached the ${maxFiles}-file limit.`);
+  return { files, warnings };
+}
+
+function scanProject(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  const adapters = options.adapters || [new JavaScriptAdapter()];
+  const commit = currentCommit(root);
+  const discovered = sourceFiles(root, adapters, options);
+  const scans = [];
+  const warnings = [...discovered.warnings];
+  for (const source of discovered.files) {
+    try {
+      scans.push(source.adapter.scan({ projectRoot: root, file: source.file, relative: source.relative, commit }));
+    } catch (error) {
+      warnings.push(`Failed to scan ${posix(source.relative)}: ${error.message}`);
+    }
+  }
+
+  const nodes = scans.flatMap((scan) => [scan.module, ...scan.symbols]);
+  const edges = [];
+  for (const scan of scans) {
+    for (const symbol of scan.symbols) {
+      edges.push({ from: symbol.id, relation: "defined_in", to: scan.module.id, evidence: `${symbol.path}:${symbol.line}`, confidence: "structural" });
+      for (const dependency of scan.dependencies) {
+        edges.push({ from: symbol.id, relation: "depends_on", to: dependency.target, evidence: `${symbol.path}:import:${dependency.specifier}`, confidence: "module" });
+      }
+    }
+    for (const dependency of scan.dependencies) {
+      edges.push({ from: scan.module.id, relation: "depends_on", to: dependency.target, evidence: `${scan.module.path}:import:${dependency.specifier}`, confidence: "module" });
+    }
+  }
+
+  const references = new Map();
+  for (const scan of scans) {
+    const identifiers = new Set(scan.masked.match(/[A-Za-z_$][\w$]*/g) || []);
+    for (const identifier of identifiers) {
+      if (!references.has(identifier)) references.set(identifier, []);
+      references.get(identifier).push(scan);
+    }
+  }
+  const symbols = nodes.filter((node) => node.kind !== "module");
+  for (const symbol of symbols) {
+    for (const scan of references.get(symbol.name) || []) {
+      if (scan.module.path === symbol.path) continue;
+      const test = TEST_FILE.test(scan.module.path);
+      edges.push({
+        from: symbol.id,
+        relation: test ? "protected_by" : "used_by",
+        to: test ? `test:${scan.module.path}` : scan.module.id,
+        evidence: `${scan.module.path}:lexical-reference:${symbol.name}`,
+        confidence: "lexical"
+      });
+    }
+  }
+
+  const uniqueEdges = new Map();
+  for (const edge of edges) uniqueEdges.set(`${edge.from}\0${edge.relation}\0${edge.to}\0${edge.evidence}`, edge);
+  return {
+    adapterIds: adapters.map((adapter) => adapter.id),
+    commit,
+    nodes: nodes.map(({ start, end, ...node }) => node),
+    edges: [...uniqueEdges.values()].sort((a, b) => `${a.from}\0${a.relation}\0${a.to}`.localeCompare(`${b.from}\0${b.relation}\0${b.to}`)),
+    files: scans.length,
+    warnings
+  };
+}
+
+module.exports = { EXCLUDED, TEST_FILE, currentCommit, scanProject, sourceFiles };

package/lib/commands/manifest.js

@@ -0,0 +1,109 @@
+"use strict";
+
+const { METHOD_VERSION } = require("../v2/schema");
+
+const nouns = Object.freeze({
+  plan: {
+    description: "turn intent into Features, Tasks, Sprints, and Runs",
+    subjects: {
+      task: ["--add [--type fix] [--status backlog]", "--list", "--show", "--run", "--audit", "--cancel", "--retry"],
+      sprint: ["--add", "--list", "--show", "--start", "--complete", "--block"],
+      feature: ["--add", "--list", "--show", "--activate", "--complete"],
+      run: ["--list", "--show", "--validate", "--learn", "--complete", "--resume", "--fail", "--block"],
+      intake: ["<request>", "--request", "--approve"],
+      challenge: ["<question>"]
+    }
+  },
+  knowledge: {
+    description: "manage evidence-backed project memory and bounded context",
+    subjects: {
+      fact: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--approve [--evidence] [--note]", "--reject [--note]", "--deprecate [--note]", "--invalidate [--note]"],
+      decision: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--resolve [--evidence] [--note]", "--deprecate [--note]", "--invalidate [--note]"],
+      insight: ["--propose [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--confidence] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--confirm [--evidence] [--note]", "--stale [--note]", "--reject [--note]", "--deprecate [--note]", "--invalidate [--note]"],
+      dossier: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--refresh [--evidence] [--note]", "--stale [--note]", "--deprecate [--note]", "--archive [--note]"],
+      context: ["--build", "--update", "--show", "--clear"],
+      map: ["--build", "--show"],
+      study: ["<focus>"],
+      vault: ["--add", "--list", "--show", "--remove", "--path"]
+    }
+  },
+  rules: {
+    description: "manage mandatory project guardrails and reviewers",
+    subjects: {
+      guardrail: ["--add", "--list", "--show", "--retire"],
+      reviewer: ["--add", "--list", "--show", "--run"]
+    }
+  },
+  review: {
+    description: "run scoped evidence-based quality gates",
+    subjects: {
+      code: ["--run"],
+      artifact: ["--run"],
+      migration: ["--run"],
+      release: ["--run"]
+    }
+  },
+  config: {
+    description: "manage project preferences, lifecycle, migration, and help",
+    subjects: {
+      project: ["--show", "--language", "--interaction", "--approval", "--quick-tasks"],
+      init: ["--local", "--shared", "--lean", "--no-agent-hint", "--force"],
+      update: ["all [--migrate]", "codex [--migrate]", "opencode [--migrate]", "claude [--migrate]"],
+      migrate: ["--to 2 --dry-run", "--to 2 --apply", "--to 2 --rollback"],
+      doctor: ["all [--strict]", "codex [--strict]", "opencode [--strict]", "claude [--strict]"],
+      uninstall: ["--force"],
+      help: ["<topic>"]
+    }
+  }
+});
+
+const aliases = Object.freeze({
+  "sc-sprint": { target: ["plan", "sprint"] },
+  "sc-fix": { target: ["plan", "task"], note: "Treat the Task as type fix." },
+  "sc-feature": { target: ["plan", "feature"] },
+  "sc-backlog": { target: ["plan", "task"], note: "Treat the Task status as backlog." },
+  "sc-goal": { target: ["plan", "feature"], note: "Treat this as the main project initiative." },
+  "sc-decisions": { target: ["knowledge", "decision"] },
+  "sc-intake": { target: ["plan", "intake"] },
+  "sc-challenge": { target: ["plan", "challenge"] },
+  "sc-know": { target: ["knowledge", "fact"] },
+  "sc-vault": { target: ["knowledge", "vault"] },
+  "sc-context": { target: ["knowledge", "context"] },
+  "sc-map": { target: ["knowledge", "map"] },
+  "sc-study": { target: ["knowledge", "study"] },
+  "sc-golden": { target: ["rules", "guardrail"] },
+  "sc-agent": { target: ["rules", "reviewer"] },
+  "sc-review": { target: ["review", "code"] },
+  "sc-config": { target: ["config", "project"] },
+  "sc-help": { target: ["config", "help"] },
+  "sc-init": { target: ["config", "init"] },
+  "sc-uninstall": { target: ["config", "uninstall"] },
+  "sc-update": { target: ["config", "update"] }
+});
+
+function resolveRoute(parts) {
+  const [noun, subject, ...args] = parts;
+  if (!noun) return { type: "help", level: "root" };
+  const nounSpec = nouns[noun];
+  if (!nounSpec) return { type: "error", message: `Unknown ScrumRun noun: ${noun}` };
+  if (!subject) return { type: "help", level: "noun", noun, spec: nounSpec };
+  if (!nounSpec.subjects[subject]) return { type: "error", message: `Unknown ${noun} subject: ${subject}` };
+  const actions = nounSpec.subjects[subject];
+  if (!args.length) return { type: "help", level: "subject", noun, subject, actions };
+  const acceptsNaturalLanguage = actions.some((action) => action.startsWith("<"));
+  if (acceptsNaturalLanguage && !args[0].startsWith("-")) return { type: "route", noun, subject, args, actions };
+  const declaredFlags = [...new Set(actions.flatMap((action) => action.match(/--[a-z0-9-]+/g) || []))];
+  const unknownFlag = args.find((arg) => arg.startsWith("-") && declaredFlags.length && !declaredFlags.includes(arg));
+  if (unknownFlag) {
+    return { type: "error", message: `Unknown ${noun} ${subject} action: ${unknownFlag}` };
+  }
+  return { type: "route", noun, subject, args, actions };
+}
+
+function resolveAlias(alias, args = []) {
+  const spec = aliases[alias];
+  if (!spec) return null;
+  return { alias, noun: spec.target[0], subject: spec.target[1], args, note: spec.note || null };
+}
+
+module.exports = { METHOD_VERSION, aliases, nouns, resolveAlias, resolveRoute };

package/lib/commands/render.js

@@ -0,0 +1,75 @@
+"use strict";
+
+const { METHOD_VERSION, aliases, nouns } = require("./manifest");
+
+function grammarLines() {
+  return Object.entries(nouns).flatMap(([noun, spec]) => [
+    `- **${noun}** — ${spec.description}`,
+    ...Object.entries(spec.subjects).map(([subject, actions]) => `  - \`${subject}\`: ${actions.join(", ")}`)
+  ]);
+}
+
+function renderRootPrompt() {
+  return `---
+description: ScrumRun ${METHOD_VERSION} — one root command for planning, execution, memory, rules, reviews, and configuration
+argument-hint: <noun> <subject> <action> [args]
+---
+
+Execute ScrumRun with this request: $ARGUMENTS
+
+Use the installed \`scrumrun\` skill as the authoritative workflow. This prompt is the only canonical slash-command entry point.
+
+If \`$ARGUMENTS\` is empty, show the five nouns below and the current project status; do not guess an action. Otherwise parse exactly \`/sc <noun> <subject> <action> [args]\`.
+
+## Grammar
+
+${grammarLines().join("\n")}
+
+## Execution contract
+
+- Natural-language product work enters through \`plan intake\` automatically.
+- Intake, contextualization, policy, risk, classification, and planning are read-only until explicit approval.
+- Approved work creates/updates a Task and creates a Run; a Sprint only groups Tasks when a real timebox/batch exists.
+- Run execution follows \`executing → validating → learning → completed|failed|blocked\`.
+- \`guardrails.md\` is canonical project policy; \`golden-rules.md\` is v1 compatibility only.
+- Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
+- Never print vault values or write before approval.
+- Unknown nouns, subjects, actions, ids, or ambiguous approval must produce a deterministic explanation, never a guessed mutation.
+
+Method: ${METHOD_VERSION}. Command grammar source: \`lib/commands/manifest.js\`.
+`;
+}
+
+function renderCompatibilityPrompt(alias) {
+  const spec = aliases[alias];
+  if (!spec) throw new Error(`Unknown compatibility alias: ${alias}`);
+  const target = `/sc ${spec.target.join(" ")}`;
+  return `---
+description: Deprecated ScrumRun v1 adapter — executes ${target}
+argument-hint: [action] [args]
+---
+
+Compatibility adapter for \`/${alias}\`.
+
+Execute this request now as \`${target} $ARGUMENTS\` using the installed \`scrumrun\` skill. Do not ask the user to re-enter the command and do not merely print a redirect.
+
+Emit one concise deprecation note: \`/${alias}\` becomes \`${target}\` in ScrumRun 2.0. ${spec.note || ""}
+`;
+}
+
+function renderCommandHelp() {
+  const nounLines = Object.entries(nouns).map(([noun, spec]) => `  /sc ${noun.padEnd(10)} ${spec.description}`);
+  const aliasLines = Object.entries(aliases).map(([alias, spec]) => `  /${alias.padEnd(14)} -> /sc ${spec.target.join(" ")}`);
+  return `ScrumRun ${METHOD_VERSION} command grammar:
+
+Canonical root:
+  /sc <noun> <subject> <action> [args]
+
+Nouns:
+${nounLines.join("\n")}
+
+Compatibility adapters (upgrade only; not installed for fresh v2 users):
+${aliasLines.join("\n")}`;
+}
+
+module.exports = { grammarLines, renderCommandHelp, renderCompatibilityPrompt, renderRootPrompt };