godpowers 0.15.0

package/lib/linkage.js

@@ -0,0 +1,232 @@
+/**
+ * Linkage Map Manager
+ *
+ * Bidirectional linkage between artifact elements (PRD requirements,
+ * ADRs, ARCH containers, ROADMAP milestones, STACK decisions, DESIGN
+ * tokens/components) and code files.
+ *
+ * Storage:
+ *   .godpowers/links/artifact-to-code.json   - forward map
+ *   .godpowers/links/code-to-artifact.json   - reverse map
+ *   .godpowers/links/LINKAGE-LOG.md          - append-only history
+ *
+ * Stable ID format:
+ *   PRD requirement:  P-{MUST,SHOULD,COULD}-NN  (e.g., P-MUST-01)
+ *   ADR:              ADR-NNN
+ *   ARCH container:   C-{slug}                  (e.g., C-auth-service)
+ *   ROADMAP milestone: M-{slug}                 (e.g., M-launch-v1)
+ *   STACK decision:   S-{slug}                  (e.g., S-postgres-15)
+ *   DESIGN token:     YAML path                 (e.g., colors.primary)
+ *   DESIGN component: D-{slug}                  (e.g., D-button-primary)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ID_PATTERNS = {
+  prd: /^P-(MUST|SHOULD|COULD)-\d+$/,
+  adr: /^ADR-\d+$/,
+  container: /^C-[\w-]+$/,
+  milestone: /^M-[\w-]+$/,
+  stack: /^S-[\w-]+$/,
+  story: /^STORY-[\w-]+-\d+$/,
+  design: /^D-[\w-]+$/,
+  token: /^[a-z][\w-]*\.[\w.-]+$/   // colors.primary, typography.display, etc.
+};
+
+function classifyId(id) {
+  for (const [kind, regex] of Object.entries(ID_PATTERNS)) {
+    if (regex.test(id)) return kind;
+  }
+  return 'unknown';
+}
+
+function linksDir(projectRoot) {
+  return path.join(projectRoot, '.godpowers', 'links');
+}
+
+function forwardPath(projectRoot) {
+  return path.join(linksDir(projectRoot), 'artifact-to-code.json');
+}
+
+function reversePath(projectRoot) {
+  return path.join(linksDir(projectRoot), 'code-to-artifact.json');
+}
+
+function logPath(projectRoot) {
+  return path.join(linksDir(projectRoot), 'LINKAGE-LOG.md');
+}
+
+function ensureDir(projectRoot) {
+  const dir = linksDir(projectRoot);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function readMap(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    return {};
+  }
+}
+
+function writeMap(filePath, data) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Read forward map: artifact ID -> array of file paths.
+ */
+function readForward(projectRoot) {
+  return readMap(forwardPath(projectRoot));
+}
+
+/**
+ * Read reverse map: file path -> array of artifact IDs.
+ */
+function readReverse(projectRoot) {
+  return readMap(reversePath(projectRoot));
+}
+
+/**
+ * Add a link: artifact ID <-> file path. Bidirectional, idempotent.
+ * Returns { added: bool, ... }.
+ */
+function addLink(projectRoot, artifactId, filePath, opts = {}) {
+  ensureDir(projectRoot);
+  const fwd = readForward(projectRoot);
+  const rev = readReverse(projectRoot);
+
+  const normFile = path.relative(projectRoot, path.resolve(projectRoot, filePath));
+  if (!fwd[artifactId]) fwd[artifactId] = [];
+  if (!rev[normFile]) rev[normFile] = [];
+
+  const fwdHad = fwd[artifactId].includes(normFile);
+  const revHad = rev[normFile].includes(artifactId);
+
+  if (!fwdHad) fwd[artifactId].push(normFile);
+  if (!revHad) rev[normFile].push(artifactId);
+
+  fwd[artifactId].sort();
+  rev[normFile].sort();
+
+  writeMap(forwardPath(projectRoot), fwd);
+  writeMap(reversePath(projectRoot), rev);
+
+  if (!fwdHad || !revHad) {
+    appendLog(projectRoot, `+ link: ${artifactId} <-> ${normFile}` + (opts.source ? ` (via ${opts.source})` : ''));
+  }
+  return { added: !fwdHad || !revHad, artifactId, file: normFile };
+}
+
+/**
+ * Remove a link.
+ */
+function removeLink(projectRoot, artifactId, filePath) {
+  ensureDir(projectRoot);
+  const fwd = readForward(projectRoot);
+  const rev = readReverse(projectRoot);
+  const normFile = path.relative(projectRoot, path.resolve(projectRoot, filePath));
+
+  let removed = false;
+  if (fwd[artifactId]) {
+    const before = fwd[artifactId].length;
+    fwd[artifactId] = fwd[artifactId].filter(f => f !== normFile);
+    if (fwd[artifactId].length === 0) delete fwd[artifactId];
+    if (before !== (fwd[artifactId] ? fwd[artifactId].length : 0)) removed = true;
+  }
+  if (rev[normFile]) {
+    const before = rev[normFile].length;
+    rev[normFile] = rev[normFile].filter(id => id !== artifactId);
+    if (rev[normFile].length === 0) delete rev[normFile];
+    if (before !== (rev[normFile] ? rev[normFile].length : 0)) removed = true;
+  }
+
+  writeMap(forwardPath(projectRoot), fwd);
+  writeMap(reversePath(projectRoot), rev);
+
+  if (removed) {
+    appendLog(projectRoot, `- link: ${artifactId} <-> ${normFile}`);
+  }
+  return { removed };
+}
+
+/**
+ * Query: given an artifact ID, return linked files.
+ */
+function queryByArtifact(projectRoot, artifactId) {
+  const fwd = readForward(projectRoot);
+  return fwd[artifactId] || [];
+}
+
+/**
+ * Query: given a file path, return linked artifact IDs.
+ */
+function queryByFile(projectRoot, filePath) {
+  const rev = readReverse(projectRoot);
+  const normFile = path.relative(projectRoot, path.resolve(projectRoot, filePath));
+  return rev[normFile] || [];
+}
+
+/**
+ * List orphan artifact IDs (no implementing file).
+ * `knownIds` is an array of artifact IDs the user wants to check (typically
+ * sourced by parsing PRD/ARCH/etc. for declared IDs).
+ */
+function listOrphans(projectRoot, knownIds) {
+  const fwd = readForward(projectRoot);
+  return knownIds.filter(id => !fwd[id] || fwd[id].length === 0);
+}
+
+/**
+ * Compute coverage: percentage of known IDs that have at least one link.
+ */
+function coverage(projectRoot, knownIds) {
+  if (knownIds.length === 0) return 1;
+  const fwd = readForward(projectRoot);
+  const linked = knownIds.filter(id => fwd[id] && fwd[id].length > 0).length;
+  return linked / knownIds.length;
+}
+
+/**
+ * Append to LINKAGE-LOG.md.
+ */
+function appendLog(projectRoot, message) {
+  ensureDir(projectRoot);
+  const ts = new Date().toISOString();
+  const line = `${ts} ${message}\n`;
+  fs.appendFileSync(logPath(projectRoot), line);
+}
+
+/**
+ * Replace all links from a source (used by code-scanner to do bulk updates).
+ */
+function bulkReplaceFromSource(projectRoot, source, links) {
+  ensureDir(projectRoot);
+  const log = [];
+  for (const { artifactId, file } of links) {
+    const r = addLink(projectRoot, artifactId, file, { source });
+    if (r.added) log.push(`from ${source}: ${artifactId} -> ${file}`);
+  }
+  return { count: links.length, added: log.length };
+}
+
+module.exports = {
+  classifyId,
+  ID_PATTERNS,
+  readForward,
+  readReverse,
+  addLink,
+  removeLink,
+  queryByArtifact,
+  queryByFile,
+  listOrphans,
+  coverage,
+  appendLog,
+  bulkReplaceFromSource,
+  forwardPath,
+  reversePath,
+  logPath,
+  linksDir
+};

package/lib/meta-linter.js

@@ -0,0 +1,263 @@
+/**
+ * Meta-Linter
+ *
+ * Cross-repo invariant checks for Mode D suites. Validates:
+ *   - Byte-identical files across repos (LICENSE, .editorconfig, etc.)
+ *   - Version table consistency (declared versions match package.json)
+ *   - Shared standards drift (linter, formatter, Node version)
+ *
+ * Per locked plan answer Q2: byte-identical drift surfaces as warnings
+ * by default; hard gate via `strict: true` opt-in.
+ *
+ * Public API:
+ *   checkByteIdentical(hubPath, opts) -> findings
+ *   checkVersionTable(hubPath, opts) -> findings
+ *   checkSharedStandards(hubPath, opts) -> findings
+ *   runAll(hubPath, opts) -> { findings, summary }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const detector = require('./multi-repo-detector');
+
+/**
+ * SHA-256 of file content. Returns null if file missing.
+ */
+function fileHash(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * For each declared byte-identical file, hash its content in each
+ * sibling repo and report mismatches.
+ */
+function checkByteIdentical(hubPath, opts = {}) {
+  const findings = [];
+  const config = detector.readSuiteConfig(hubPath);
+  if (!config) return findings;
+
+  const files = detector.getByteIdenticalFiles(hubPath);
+  if (files.length === 0) return findings;
+
+  const siblings = (config.siblings || []).map(sib => {
+    if (typeof sib === 'string') return { name: sib, path: path.resolve(hubPath, sib) };
+    return { name: sib.name, path: path.resolve(hubPath, sib.path || sib.name) };
+  });
+
+  const severity = opts.strict ? 'error' : 'warning';
+
+  for (const fileSpec of files) {
+    const filePath = fileSpec.path;
+    const hashes = {};
+    for (const sib of siblings) {
+      const full = path.join(sib.path, filePath);
+      hashes[sib.name] = fileHash(full);
+    }
+
+    const uniqueHashes = new Set(Object.values(hashes).filter(h => h !== null));
+    if (uniqueHashes.size > 1) {
+      findings.push({
+        severity,
+        kind: 'byte-identical-drift',
+        file: filePath,
+        message: `File "${filePath}" differs across repos. Hashes:`,
+        hashes
+      });
+    }
+    // Missing in some siblings is also a drift
+    for (const [repo, hash] of Object.entries(hashes)) {
+      if (hash === null) {
+        findings.push({
+          severity,
+          kind: 'byte-identical-missing',
+          file: filePath,
+          repo,
+          message: `Byte-identical file "${filePath}" is missing in repo "${repo}".`
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Verify the suite-level version table matches each repo's package.json.
+ * Strictness setting same as byte-identical.
+ */
+function checkVersionTable(hubPath, opts = {}) {
+  const findings = [];
+  const config = detector.readSuiteConfig(hubPath);
+  if (!config) return findings;
+
+  const versionTable = detector.getVersionTable(hubPath);
+  if (Object.keys(versionTable).length === 0) return findings;
+
+  const severity = opts.strict ? 'error' : 'warning';
+
+  const siblings = (config.siblings || []).map(sib => {
+    if (typeof sib === 'string') return { name: sib, path: path.resolve(hubPath, sib) };
+    return { name: sib.name, path: path.resolve(hubPath, sib.path || sib.name) };
+  });
+
+  for (const [packageName, perRepoVersions] of Object.entries(versionTable)) {
+    for (const [repoName, declaredVersion] of Object.entries(perRepoVersions)) {
+      const sib = siblings.find(s => s.name === repoName);
+      if (!sib) continue;
+      const pkgPath = path.join(sib.path, 'package.json');
+      if (!fs.existsSync(pkgPath)) continue;
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (packageName === repoName) {
+          // The repo's own version
+          if (pkg.version !== declaredVersion) {
+            findings.push({
+              severity,
+              kind: 'version-table-drift',
+              repo: repoName,
+              package: packageName,
+              declared: declaredVersion,
+              actual: pkg.version,
+              message: `Suite declares ${repoName} at ${declaredVersion}; package.json has ${pkg.version}.`
+            });
+          }
+        } else if (allDeps[packageName]) {
+          // A sibling's dependency on packageName
+          const actualSpec = String(allDeps[packageName]).replace(/^[\^~>=<]+/, '');
+          if (actualSpec.split('.')[0] !== declaredVersion.split('.')[0]) {
+            findings.push({
+              severity,
+              kind: 'version-table-drift',
+              repo: repoName,
+              package: packageName,
+              declared: declaredVersion,
+              actual: allDeps[packageName],
+              message: `Suite declares ${packageName} at ${declaredVersion} for ${repoName}; package.json has ${allDeps[packageName]}.`
+            });
+          }
+        }
+      } catch (e) {
+        // ignore parse errors
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Validate shared standards: all repos use the same linter, formatter,
+ * Node version, etc. Declared in suite-config under `shared-standards`.
+ */
+function checkSharedStandards(hubPath, opts = {}) {
+  const findings = [];
+  const config = detector.readSuiteConfig(hubPath);
+  if (!config) return findings;
+  const standards = config['shared-standards'] || config.sharedStandards;
+  if (!standards) return findings;
+
+  const severity = opts.strict ? 'error' : 'warning';
+
+  const siblings = (config.siblings || []).map(sib => {
+    if (typeof sib === 'string') return { name: sib, path: path.resolve(hubPath, sib) };
+    return { name: sib.name, path: path.resolve(hubPath, sib.path || sib.name) };
+  });
+
+  // Node version (from .nvmrc or engines.node)
+  if (standards['node-version']) {
+    const expected = standards['node-version'];
+    for (const sib of siblings) {
+      const nvmrc = path.join(sib.path, '.nvmrc');
+      const pkg = path.join(sib.path, 'package.json');
+      let actual = null;
+      if (fs.existsSync(nvmrc)) {
+        actual = fs.readFileSync(nvmrc, 'utf8').trim();
+      } else if (fs.existsSync(pkg)) {
+        try {
+          const j = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+          actual = j.engines && j.engines.node;
+        } catch (e) {
+          // ignore
+        }
+      }
+      if (actual && !String(actual).includes(String(expected).split('.')[0])) {
+        findings.push({
+          severity,
+          kind: 'shared-standard-drift',
+          repo: sib.name,
+          standard: 'node-version',
+          declared: expected,
+          actual,
+          message: `Repo ${sib.name} uses Node ${actual}; suite declares ${expected}.`
+        });
+      }
+    }
+  }
+
+  // Linter
+  if (standards.linter) {
+    const expected = standards.linter; // 'biome', 'eslint', etc.
+    for (const sib of siblings) {
+      const pkg = path.join(sib.path, 'package.json');
+      if (!fs.existsSync(pkg)) continue;
+      try {
+        const j = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+        const allDeps = { ...j.dependencies, ...j.devDependencies };
+        const usesBiome = allDeps['@biomejs/biome'] || allDeps.biome;
+        const usesEslint = allDeps.eslint || Object.keys(allDeps).some(k => k.startsWith('eslint-'));
+        let detected = null;
+        if (usesBiome) detected = 'biome';
+        else if (usesEslint) detected = 'eslint';
+        if (detected && detected !== expected) {
+          findings.push({
+            severity,
+            kind: 'shared-standard-drift',
+            repo: sib.name,
+            standard: 'linter',
+            declared: expected,
+            actual: detected,
+            message: `Repo ${sib.name} uses ${detected}; suite declares ${expected}.`
+          });
+        }
+      } catch (e) {
+        // ignore
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Run all meta-lint checks.
+ */
+function runAll(hubPath, opts = {}) {
+  const findings = [
+    ...checkByteIdentical(hubPath, opts),
+    ...checkVersionTable(hubPath, opts),
+    ...checkSharedStandards(hubPath, opts)
+  ];
+  const summary = {
+    errors: findings.filter(f => f.severity === 'error').length,
+    warnings: findings.filter(f => f.severity === 'warning').length,
+    infos: findings.filter(f => f.severity === 'info').length,
+    byKind: {}
+  };
+  for (const f of findings) {
+    summary.byKind[f.kind] = (summary.byKind[f.kind] || 0) + 1;
+  }
+  return { findings, summary };
+}
+
+module.exports = {
+  checkByteIdentical,
+  checkVersionTable,
+  checkSharedStandards,
+  runAll,
+  fileHash
+};

package/lib/multi-repo-detector.js

@@ -0,0 +1,182 @@
+/**
+ * Multi-Repo Detector
+ *
+ * Detects whether the working directory is part of a multi-repo suite
+ * (Mode D in the repo-ready taxonomy).
+ *
+ * Detection signals (any one is enough):
+ *   1. `.godpowers/suite-config.yaml` declares siblings (canonical)
+ *   2. Multiple `.godpowers/` dirs under a common parent that user
+ *      explicitly registered (via /god-suite-init)
+ *   3. Hub indicator: directory contains a suite-config.yaml AND has
+ *      no source code of its own (pure coordination repo)
+ *
+ * Per the locked plan answer Q1: explicit declaration only. We do NOT
+ * auto-walk parent dirs to find siblings. Users must register them.
+ *
+ * Public API:
+ *   detect(projectRoot) -> { isMultiRepo, role, siblings, hubPath }
+ *   readSuiteConfig(projectRoot) -> { siblings, byteIdentical, ... } | null
+ *   isHub(projectRoot) -> bool
+ *   findHub(projectRoot) -> hubPath | null
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseSimpleYaml } = require('./intent');
+
+/**
+ * Look for .godpowers/suite-config.yaml in projectRoot or any
+ * registered parent. Returns parsed content or null.
+ */
+function readSuiteConfig(projectRoot) {
+  const localConfig = path.join(projectRoot, '.godpowers', 'suite-config.yaml');
+  if (fs.existsSync(localConfig)) {
+    try {
+      const content = fs.readFileSync(localConfig, 'utf8');
+      return parseSimpleYaml(content);
+    } catch (e) {
+      return null;
+    }
+  }
+  // Check if state.json points to a hub
+  const statePath = path.join(projectRoot, '.godpowers', 'state.json');
+  if (fs.existsSync(statePath)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      if (state.suite && state.suite.hubPath) {
+        const hubConfigPath = path.join(state.suite.hubPath, '.godpowers', 'suite-config.yaml');
+        if (fs.existsSync(hubConfigPath)) {
+          return parseSimpleYaml(fs.readFileSync(hubConfigPath, 'utf8'));
+        }
+      }
+    } catch (e) {
+      // ignore
+    }
+  }
+  return null;
+}
+
+/**
+ * Is this directory the hub of a suite?
+ * Heuristic: has suite-config.yaml AND declares siblings AND is not
+ * itself listed in those siblings.
+ */
+function isHub(projectRoot) {
+  const config = readSuiteConfig(projectRoot);
+  if (!config) return false;
+  const siblings = (config.siblings || []).map(s => normalize(s));
+  const myName = normalize(path.basename(projectRoot));
+  return siblings.length > 0 && !siblings.includes(myName);
+}
+
+/**
+ * Find the hub from a sibling repo. Walks up via state.json.suite.hubPath.
+ * Returns hub absolute path or null.
+ */
+function findHub(projectRoot) {
+  const statePath = path.join(projectRoot, '.godpowers', 'state.json');
+  if (!fs.existsSync(statePath)) return null;
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    if (state.suite && state.suite.hubPath) {
+      return state.suite.hubPath;
+    }
+  } catch (e) {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Detect this directory's role in a suite.
+ *
+ * Returns:
+ *   {
+ *     isMultiRepo: bool,
+ *     role: 'hub' | 'sibling' | null,
+ *     siblings: [{ name, path }],   // populated when isMultiRepo
+ *     hubPath: string | null
+ *   }
+ */
+function detect(projectRoot) {
+  const config = readSuiteConfig(projectRoot);
+  if (!config) {
+    return { isMultiRepo: false, role: null, siblings: [], hubPath: null };
+  }
+
+  const myName = path.basename(projectRoot);
+  const declaredSiblings = config.siblings || [];
+
+  // Resolve sibling paths. Per Q1, paths are explicit (relative or absolute)
+  // in suite-config.yaml.
+  const siblingsResolved = declaredSiblings.map(sib => {
+    if (typeof sib === 'string') {
+      return { name: sib, path: path.resolve(projectRoot, sib) };
+    }
+    if (typeof sib === 'object' && sib.name) {
+      return {
+        name: sib.name,
+        path: sib.path ? path.resolve(projectRoot, sib.path) : null
+      };
+    }
+    return null;
+  }).filter(Boolean);
+
+  const isCurrentHub = isHub(projectRoot);
+
+  if (isCurrentHub) {
+    return {
+      isMultiRepo: true,
+      role: 'hub',
+      siblings: siblingsResolved,
+      hubPath: projectRoot
+    };
+  }
+
+  // We're a sibling. Find the hub.
+  const hubPath = findHub(projectRoot);
+  return {
+    isMultiRepo: !!hubPath,
+    role: hubPath ? 'sibling' : null,
+    siblings: siblingsResolved,
+    hubPath
+  };
+}
+
+/**
+ * List byte-identical files declared in the suite config.
+ * Returns [{ path, description }].
+ */
+function getByteIdenticalFiles(projectRoot) {
+  const config = readSuiteConfig(projectRoot);
+  if (!config) return [];
+  const list = config['byte-identical'] || config.byteIdentical || [];
+  return list.map(item => {
+    if (typeof item === 'string') return { path: item, description: '' };
+    return { path: item.path, description: item.description || '' };
+  });
+}
+
+/**
+ * Get the version table from suite-config.
+ * Format: { 'package-name': { 'repo-name': '1.2.3' } }
+ */
+function getVersionTable(projectRoot) {
+  const config = readSuiteConfig(projectRoot);
+  if (!config) return {};
+  return config['version-table'] || config.versionTable || {};
+}
+
+function normalize(name) {
+  return String(name || '').toLowerCase().trim();
+}
+
+module.exports = {
+  detect,
+  readSuiteConfig,
+  isHub,
+  findHub,
+  getByteIdenticalFiles,
+  getVersionTable
+};