dw-kit 1.3.5 → 1.4.0

package/src/lib/config.mjs

@@ -1,104 +1,120 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import yaml from 'js-yaml';
-
-export function loadConfig(configPath) {
-  if (!existsSync(configPath)) return null;
-  const content = readFileSync(configPath, 'utf-8');
-  return yaml.load(content);
-}
-
-/**
- * Load config với local override (v1.2+).
- * dw.config.yml  — shared, committed
- * dw.config.local.yml — machine-specific, gitignored
- * Local values win over base values (shallow merge per top-level key).
- */
-export function loadConfigWithLocal(configDir) {
-  const basePath = `${configDir}/dw.config.yml`;
-  const localPath = `${configDir}/dw.config.local.yml`;
-
-  const base = loadConfig(basePath);
-  if (!base) return null;
-
-  if (!existsSync(localPath)) return base;
-
-  const local = loadConfig(localPath);
-  if (!local) return base;
-
-  const merged = { ...base };
-  for (const key of Object.keys(local)) {
-    if (typeof local[key] === 'object' && !Array.isArray(local[key]) && local[key] !== null) {
-      merged[key] = { ...(merged[key] || {}), ...local[key] };
-    } else {
-      merged[key] = local[key];
-    }
-  }
-  return merged;
-}
-
-export function writeConfig(configPath, data) {
-  const content = yaml.dump(data, {
-    indent: 2,
-    lineWidth: -1,
-    quotingType: '"',
-    forceQuotes: false,
-    noRefs: true,
-  });
-  writeFileSync(configPath, content, 'utf-8');
-}
-
-export function loadSchema(schemaPath) {
-  if (!existsSync(schemaPath)) return null;
-  return JSON.parse(readFileSync(schemaPath, 'utf-8'));
-}
-
-export function buildConfig({ projectName, language, depth, roles }) {
-  const today = new Date().toISOString().split('T')[0];
-  return {
-    project: {
-      name: projectName,
-      language: language,
-    },
-    workflow: {
-      default_depth: depth,
-    },
-    team: {
-      roles: roles,
-    },
-    quality: {
-      test_command: '',
-      lint_command: '',
-      block_on_fail: false,
-    },
-    tracking: {
-      estimation: depth !== 'quick',
-      log_work: depth === 'thorough',
-      estimation_unit: 'hours',
-    },
-    paths: {
-      tasks: '.dw/tasks',
-      docs: '.dw/docs',
-    },
-    claude: {
-      models: { plan: '', execute: '', review: '' },
-      structured_output: depth !== 'quick',
-      worktree_execution: false,
-      mcp: [],
-    },
-    _toolkit: {
-      core_version: '1.2',
-      platform_version: '1.0',
-      capability_version: '1.2',
-      installed: today,
-      last_upgrade: today,
-    },
-  };
-}
-
-export function getToolkitVersions(config) {
-  return {
-    core: config?._toolkit?.core_version || 'unknown',
-    platform: config?._toolkit?.platform_version || 'unknown',
-    capability: config?._toolkit?.capability_version || 'unknown',
-  };
-}
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import yaml from 'js-yaml';
+
+export function loadConfig(configPath) {
+  if (!existsSync(configPath)) return null;
+  const content = readFileSync(configPath, 'utf-8');
+  return yaml.load(content);
+}
+
+/**
+ * Load config với local override (v1.2+).
+ * dw.config.yml  — shared, committed
+ * dw.config.local.yml — machine-specific, gitignored
+ * Local values win over base values (shallow merge per top-level key).
+ */
+export function loadConfigWithLocal(configDir) {
+  const basePath = `${configDir}/dw.config.yml`;
+  const localPath = `${configDir}/dw.config.local.yml`;
+
+  const base = loadConfig(basePath);
+  if (!base) return null;
+
+  if (!existsSync(localPath)) return base;
+
+  const local = loadConfig(localPath);
+  if (!local) return base;
+
+  const merged = { ...base };
+  for (const key of Object.keys(local)) {
+    if (typeof local[key] === 'object' && !Array.isArray(local[key]) && local[key] !== null) {
+      merged[key] = { ...(merged[key] || {}), ...local[key] };
+    } else {
+      merged[key] = local[key];
+    }
+  }
+  return merged;
+}
+
+export function writeConfig(configPath, data) {
+  const content = yaml.dump(data, {
+    indent: 2,
+    lineWidth: -1,
+    quotingType: '"',
+    forceQuotes: false,
+    noRefs: true,
+  });
+  writeFileSync(configPath, content, 'utf-8');
+}
+
+export function loadSchema(schemaPath) {
+  if (!existsSync(schemaPath)) return null;
+  return JSON.parse(readFileSync(schemaPath, 'utf-8'));
+}
+
+export function buildConfig({ projectName, language, depth, roles }) {
+  const today = new Date().toISOString().split('T')[0];
+  return {
+    project: {
+      name: projectName,
+      language: language,
+    },
+    workflow: {
+      default_depth: depth,
+    },
+    team: {
+      roles: roles,
+    },
+    quality: {
+      test_command: '',
+      lint_command: '',
+      block_on_fail: false,
+    },
+    tracking: {
+      estimation: depth !== 'quick',
+      log_work: depth === 'thorough',
+      estimation_unit: 'hours',
+    },
+    paths: {
+      tasks: '.dw/tasks',
+      docs: '.dw/docs',
+    },
+    claude: {
+      models: { plan: '', execute: '', review: '' },
+      structured_output: depth !== 'quick',
+      worktree_execution: false,
+      mcp: [],
+    },
+    _toolkit: {
+      core_version: '1.2',
+      platform_version: '1.0',
+      capability_version: '1.2',
+      installed: today,
+      last_upgrade: today,
+    },
+  };
+}
+
+export function getToolkitVersions(config) {
+  return {
+    core: config?._toolkit?.core_version || 'unknown',
+    platform: config?._toolkit?.platform_version || 'unknown',
+    capability: config?._toolkit?.capability_version || 'unknown',
+  };
+}
+
+/**
+ * Renderer config for /dw:review --visual + `dw review render` (ADR-0007).
+ * Falls back to defaults when keys are absent so existing projects work
+ * without re-running `dw init`.
+ */
+export function getReviewRendererConfig(config) {
+  const r = config?.claude?.review?.renderer || {};
+  return {
+    strategy: r.strategy || 'auto',
+    theme: r.theme || 'github-dark',
+    font: r.font || 'JetBrains Mono',
+    formats: Array.isArray(r.formats) && r.formats.length ? r.formats : ['svg', 'png'],
+    output_dir: r.output_dir || '.dw/reviews',
+  };
+}

package/src/lib/gitignore.mjs

@@ -53,7 +53,11 @@ function applyManagedBlock(content, blockLines) {
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
     const before = content.slice(0, startIdx);
     const after = content.slice(endIdx + MARKER_END.length);
-    return (before + block + after).replace(/\n{3,}/g, '\n\n');
+    // Collapse multiple consecutive blanks AND normalize trailing whitespace
+    // so re-running the helper is byte-identical (required by smoke idempotency test).
+    return (before + block + after)
+      .replace(/\n{3,}/g, '\n\n')
+      .replace(/\n+$/, '\n');
   }
 
   // Markers not present — append block

package/src/lib/npm-registry.mjs

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const REGISTRY_BASE = 'https://registry.npmjs.org';
+const FETCH_TIMEOUT_MS = 5000;
+const CACHE_REL = '.dw/security/npm-registry-cache.jsonl';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour per ADR-0006
+
+export function cachePath(rootDir = process.cwd()) {
+  return join(rootDir, CACHE_REL);
+}
+
+function ensureCacheDir(rootDir) {
+  const dir = dirname(cachePath(rootDir));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function loadCache(rootDir = process.cwd()) {
+  const p = cachePath(rootDir);
+  if (!existsSync(p)) return new Map();
+  const map = new Map();
+  try {
+    const lines = readFileSync(p, 'utf-8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const e = JSON.parse(line);
+        if (e && e.key) map.set(e.key, e);
+      } catch {
+        // skip malformed line
+      }
+    }
+  } catch {
+    // unreadable cache → ignore
+  }
+  return map;
+}
+
+export function cacheGet(rootDir, key, ttlMs = CACHE_TTL_MS) {
+  const map = loadCache(rootDir);
+  const entry = map.get(key);
+  if (!entry) return null;
+  if (ttlMs <= 0) return null;
+  if (Date.now() - entry.cached_at > ttlMs) return null;
+  return entry.value;
+}
+
+export function cachePut(rootDir, key, value) {
+  ensureCacheDir(rootDir);
+  const line = JSON.stringify({ key, cached_at: Date.now(), value }) + '\n';
+  appendFileSync(cachePath(rootDir), line, 'utf-8');
+}
+
+export function pruneCache(rootDir, ttlMs = CACHE_TTL_MS) {
+  const p = cachePath(rootDir);
+  if (!existsSync(p)) return;
+  const map = loadCache(rootDir);
+  const now = Date.now();
+  const fresh = [];
+  for (const e of map.values()) {
+    if (now - e.cached_at <= ttlMs) fresh.push(e);
+  }
+  ensureCacheDir(rootDir);
+  writeFileSync(p, fresh.map((e) => JSON.stringify(e)).join('\n') + (fresh.length ? '\n' : ''), 'utf-8');
+}
+
+async function fetchJson(url, { timeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const err = new Error(`npm registry HTTP ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Fetch the full registry document for a package. Cached.
+ * Returns the raw npm registry response or null on hard failure.
+ */
+export async function fetchPackageMetadata(packageName, rootDir = process.cwd(), { useCache = true } = {}) {
+  const key = `pkg:${packageName}`;
+  if (useCache) {
+    const cached = cacheGet(rootDir, key);
+    if (cached) return cached;
+  }
+  try {
+    const data = await fetchJson(`${REGISTRY_BASE}/${encodeURIComponent(packageName).replace('%40', '@')}`);
+    cachePut(rootDir, key, data);
+    return data;
+  } catch (e) {
+    if (e.status === 404) return null;
+    throw e;
+  }
+}
+
+/**
+ * Extract the signals needed by the heuristic scorer (ADR-0006 pillar 3).
+ * Pure function — call after fetchPackageMetadata returned a document.
+ */
+export function extractSignals(metadata, version) {
+  if (!metadata) return null;
+  const timeMap = metadata.time || {};
+  const publishIso = timeMap[version] || null;
+  const publishedAt = publishIso ? new Date(publishIso).getTime() : null;
+  const ageHours = publishedAt ? (Date.now() - publishedAt) / (1000 * 60 * 60) : null;
+
+  // Last modified time on the package as a whole — proxy for maintainer activity
+  const modifiedIso = timeMap.modified || null;
+  const modifiedAt = modifiedIso ? new Date(modifiedIso).getTime() : null;
+
+  // Maintainer set
+  const maintainers = Array.isArray(metadata.maintainers)
+    ? metadata.maintainers.map((m) => (typeof m === 'string' ? m : m.name)).filter(Boolean)
+    : [];
+
+  // Latest version on dist-tags
+  const latestVersion = metadata['dist-tags']?.latest || null;
+
+  return {
+    package: metadata.name,
+    version,
+    publish_iso: publishIso,
+    publish_age_hours: ageHours,
+    latest_version: latestVersion,
+    modified_iso: modifiedIso,
+    package_modified_age_days: modifiedAt ? (Date.now() - modifiedAt) / (1000 * 60 * 60 * 24) : null,
+    maintainer_count: maintainers.length,
+    maintainers,
+  };
+}
+
+/**
+ * Lightweight popularity probe via downloads API. Cached separately.
+ * Returns weekly downloads count or null on failure.
+ */
+export async function fetchWeeklyDownloads(packageName, rootDir = process.cwd(), { useCache = true } = {}) {
+  const key = `dl:${packageName}`;
+  if (useCache) {
+    const cached = cacheGet(rootDir, key);
+    if (cached) return cached;
+  }
+  try {
+    const data = await fetchJson(`https://api.npmjs.org/downloads/point/last-week/${encodeURIComponent(packageName).replace('%40', '@')}`);
+    const count = typeof data?.downloads === 'number' ? data.downloads : null;
+    cachePut(rootDir, key, count);
+    return count;
+  } catch {
+    return null;
+  }
+}

package/src/lib/review/manifest-schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/schemas/review-manifest.json",
+  "title": "dw-kit Review Render Manifest",
+  "description": "Structured findings manifest produced by /dw:review --visual and consumed by `dw review render` + dw-kit-render. Versioned public API surface — see ADR-0007.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "scope", "generated_at", "findings"],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Manifest schema version. Renderer rejects mismatched versions with clear error."
+    },
+    "scope": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Review scope identifier (branch slug, task slug, or arbitrary label). NOT used directly as path — caller must sanitize via scope-slug util."
+    },
+    "scope_slug": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "pattern": "^[a-zA-Z0-9._-]+$",
+      "description": "Sanitized scope used as directory name under .dw/reviews/. Filesystem-safe on Windows + POSIX."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when manifest was produced."
+    },
+    "task_id": {
+      "type": "string",
+      "description": "Optional link to .dw/tasks/{task_id}/ — enables /dw:execute to load findings as fix targets."
+    },
+    "review_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reviewer": { "type": "string", "description": "Skill or agent name that produced this manifest (e.g. 'dw-review')." },
+        "depth": { "type": "string", "enum": ["quick", "standard", "thorough"] },
+        "diff_base": { "type": "string", "description": "Git ref the review was computed against (e.g. 'main', 'origin/dev')." },
+        "files_reviewed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "minItems": 0,
+      "items": { "$ref": "#/definitions/finding" }
+    }
+  },
+  "definitions": {
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "severity", "title", "location", "body"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9._-]+$",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Unique finding ID within the manifest. Used as artifact filename: finding-{id}.svg / .png."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["critical", "warning", "suggestion"],
+          "description": "Drives banner color in rendered artifact."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "One-line summary shown as the card heading."
+        },
+        "location": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["file"],
+          "properties": {
+            "file": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Repo-relative path. Forward slashes regardless of OS."
+            },
+            "line_start": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "First relevant line (1-indexed)."
+            },
+            "line_end": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Last relevant line (1-indexed, inclusive)."
+            }
+          }
+        },
+        "rule_ref": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Optional rule/standard reference shown in card subhead."
+        },
+        "body": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000,
+          "description": "Finding explanation (markdown allowed in rendered output, plain text safe fallback)."
+        },
+        "fix": {
+          "type": "string",
+          "maxLength": 4000,
+          "description": "Optional concrete fix suggestion shown as action banner."
+        },
+        "code_snippet": {
+          "type": "string",
+          "maxLength": 8000,
+          "description": "Raw code lines from `location` range. Pulled by the LLM during manifest generation; renderer does not re-read source files. Cap at ~50 lines around finding."
+        },
+        "language": {
+          "type": "string",
+          "maxLength": 32,
+          "description": "Language identifier for syntax highlighting (e.g. javascript, python, go). Defaults to plain text in renderer if absent or unknown."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "location": {
+                "required": ["line_start", "line_end"]
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "location": {
+                "properties": {
+                  "line_end": { "type": "integer" },
+                  "line_start": { "type": "integer" }
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/src/lib/review/manifest-validator.mjs

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import Ajv from 'ajv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = resolve(__dirname, 'manifest-schema.json');
+
+let _schema = null;
+let _ajv = null;
+let _validate = null;
+
+export const CURRENT_SCHEMA_VERSION = 1;
+
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/;
+
+function getSchema() {
+  if (!_schema) {
+    _schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf-8'));
+  }
+  return _schema;
+}
+
+function getValidator() {
+  if (_validate) return _validate;
+  _ajv = new Ajv({ allErrors: true, strict: false });
+  _ajv.addFormat('date-time', ISO_DATE_TIME);
+  _validate = _ajv.compile(getSchema());
+  return _validate;
+}
+
+/**
+ * Validate a manifest object against the schema.
+ *
+ * @param {object} manifest - parsed manifest JSON
+ * @returns {{ok: boolean, errors: Array<{path: string, message: string}>}}
+ */
+export function validateManifest(manifest) {
+  if (manifest == null || typeof manifest !== 'object') {
+    return { ok: false, errors: [{ path: '', message: 'manifest must be an object' }] };
+  }
+  if (Number.isInteger(manifest.schema_version) && manifest.schema_version !== CURRENT_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      errors: [{
+        path: '/schema_version',
+        message: `unsupported schema_version=${manifest.schema_version}; renderer supports ${CURRENT_SCHEMA_VERSION}. Upgrade dw-kit or regenerate manifest.`,
+      }],
+    };
+  }
+  const validate = getValidator();
+  const valid = validate(manifest);
+  if (valid) return { ok: true, errors: [] };
+  const errors = (validate.errors || []).map((e) => ({
+    path: e.instancePath || '/',
+    message: `${e.message}${e.params && Object.keys(e.params).length ? ' (' + JSON.stringify(e.params) + ')' : ''}`,
+  }));
+  return { ok: false, errors };
+}
+
+/**
+ * Parse + validate from JSON string.
+ *
+ * @param {string} jsonText
+ * @returns {{ok: boolean, manifest?: object, errors: Array}}
+ */
+export function parseManifest(jsonText) {
+  let manifest;
+  try {
+    manifest = JSON.parse(jsonText);
+  } catch (e) {
+    return { ok: false, errors: [{ path: '', message: `invalid JSON: ${e.message}` }] };
+  }
+  const result = validateManifest(manifest);
+  if (!result.ok) return { ok: false, errors: result.errors };
+  return { ok: true, manifest, errors: [] };
+}
+
+/**
+ * Read + validate manifest file from disk.
+ *
+ * @param {string} manifestPath
+ * @returns {{ok: boolean, manifest?: object, errors: Array}}
+ */
+export function readManifest(manifestPath) {
+  let text;
+  try {
+    text = readFileSync(manifestPath, 'utf-8');
+  } catch (e) {
+    return { ok: false, errors: [{ path: '', message: `cannot read manifest: ${e.message}` }] };
+  }
+  return parseManifest(text);
+}