macca-method 2.1.2 → 3.0.0-rc.1

package/scripts/validate-docs.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const documentationFiles = [
+  "README.md", "docs/workflows.md", "docs/configuration.md", "docs/troubleshooting.md",
+];
+const blank = (text) => text.replace(/[^\r\n]/g, " ");
+
+// Preserve offsets so section extraction and diagnostics refer to source text.
+function stripCode(source, inline = true) {
+  let fence = null;
+  let text = source.split(/(?<=\n)/).map((line) => {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})([^\r\n]*)/);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) fence = null;
+      return blank(line);
+    }
+    if (marker && !(marker[1][0] === "`" && marker[2].includes("`"))) {
+      fence = marker[1];
+      return blank(line);
+    }
+    return /^(?: {4}|\t)/.test(line) ? blank(line) : line;
+  }).join("").replace(/<!--[\s\S]*?-->/g, blank);
+  if (inline) text = text.replace(/(`+)(?!`)([\s\S]*?[^`])\1(?!`)/g, blank);
+  return text;
+}
+
+function destinationAt(text, start) {
+  let index = start;
+  while (/\s/.test(text[index] || "") && index < text.length) index++;
+  if (text[index] === "<") {
+    const end = text.indexOf(">", index + 1);
+    if (end >= 0) return { destination: text.slice(index + 1, end), end: end + 1 };
+    return null;
+  }
+  const begin = index;
+  let depth = 0;
+  for (; index < text.length; index++) {
+    const character = text[index];
+    if (character === "\\") { index++; continue; }
+    if (character === "(") depth++;
+    if (character === ")") {
+      if (!depth) break;
+      depth--;
+    }
+    if (/\s/.test(character) && !depth) break;
+  }
+  return depth ? null : { destination: text.slice(begin, index), end: index };
+}
+
+function markdownLinks(source) {
+  let text = stripCode(source);
+  const definitions = new Map();
+  const normalize = (label) => label.trim().replace(/\s+/g, " ").toLowerCase();
+  text = text.replace(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(.+)$/gm, (line, label, value) => {
+    const parsed = destinationAt(value, 0);
+    if (parsed && !definitions.has(normalize(label))) definitions.set(normalize(label), parsed.destination);
+    return blank(line);
+  });
+  const links = [];
+  // Inline links and images share the same destination syntax. Backticked
+  // filenames and example commands are not links and have already been masked.
+  let consumed = 0;
+  for (const match of text.matchAll(/(?<!\\)\[([^\]\n]*)\]/g)) {
+    if (match.index < consumed) continue;
+    const end = match.index + match[0].length;
+    let destination;
+    if (text[end] === "(") {
+      const parsed = destinationAt(text, end + 1);
+      if (parsed && /^(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^\n]*?\)))?\s*\)/.test(text.slice(parsed.end))) {
+        destination = parsed.destination;
+      }
+    } else if (text[end] === "[") {
+      const reference = text.slice(end).match(/^\[([^\]\n]*)\]/);
+      if (reference) {
+        destination = definitions.get(normalize(reference[1] || match[1]));
+        consumed = end + reference[0].length;
+      }
+    } else {
+      destination = definitions.get(normalize(match[1]));
+    }
+    if (destination !== undefined) links.push({ destination, offset: match.index });
+  }
+  return links;
+}
+
+function headingAnchors(source) {
+  const anchors = new Set();
+  const text = stripCode(source, false);
+  const lines = text.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index++) {
+    const atx = lines[index].match(/^ {0,3}#{1,6}[ \t]+(.+?)(?:[ \t]+#+[ \t]*)?$/);
+    const setext = index + 1 < lines.length && /^ {0,3}(?:=+|-+)\s*$/.test(lines[index + 1]) && lines[index].trim();
+    if (!atx && !setext) continue;
+    const heading = (atx ? atx[1] : lines[index++])
+      .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+      .replace(/<[^>]*>/g, "")
+      .replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'")
+      .replace(/&#(x[\da-f]+|\d+);/gi, (entity, number) => {
+        const code = number[0].toLowerCase() === "x" ? parseInt(number.slice(1), 16) : Number(number);
+        return code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+      });
+    // GitHub keeps hyphens/underscores, removes punctuation (not replaces it
+    // with a hyphen), and retains repeated spaces as repeated hyphens.
+    const base = heading.toLowerCase().replace(/[^\p{L}\p{M}\p{N}\p{Pc}\- ]/gu, "").replace(/ /g, "-");
+    let slug = base;
+    for (let suffix = 1; anchors.has(slug); suffix++) slug = `${base}-${suffix}`;
+    anchors.add(slug);
+  }
+  return anchors;
+}
+
+function validateDocs(root, packagedFiles) {
+  const issues = [];
+  const anchors = new Map();
+  for (const file of documentationFiles) {
+    const source = fs.readFileSync(path.join(root, file), "utf8");
+    for (const { destination, offset } of markdownLinks(source)) {
+      if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(destination)) continue;
+      const label = `${file}:${source.slice(0, offset).split("\n").length}`;
+      let targetPath;
+      let fragment;
+      try {
+        const hash = destination.indexOf("#");
+        const pathname = (hash < 0 ? destination : destination.slice(0, hash)).split("?")[0];
+        targetPath = pathname ? decodeURIComponent(pathname.replace(/\\([\\()[\] ])/g, "$1")) : "";
+        fragment = hash < 0 ? "" : decodeURIComponent(destination.slice(hash + 1));
+      } catch {
+        issues.push(`${label}: invalid URL encoding in ${destination}`);
+        continue;
+      }
+      const target = targetPath ? path.resolve(root, path.dirname(file), targetPath) : path.join(root, file);
+      const relative = path.relative(root, target).split(path.sep).join("/");
+      if (relative === ".." || relative.startsWith("../") || path.isAbsolute(relative) || targetPath.startsWith("/")) {
+        issues.push(`${label}: local link escapes package: ${destination}`);
+        continue;
+      }
+      if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+        issues.push(`${label}: missing local link target: ${destination}`);
+        continue;
+      }
+      if (!packagedFiles.has(relative)) issues.push(`${label}: local link target is not packaged: ${destination}`);
+      if (fragment && /\.md$/i.test(target)) {
+        if (!anchors.has(target)) anchors.set(target, headingAnchors(fs.readFileSync(target, "utf8")));
+        if (!anchors.get(target).has(fragment)) issues.push(`${label}: missing heading anchor: ${destination}`);
+      }
+    }
+  }
+  return issues;
+}
+
+module.exports = { documentationFiles, stripCode, markdownLinks, headingAnchors, validateDocs };
+
+if (require.main === module) {
+  // The package validator supplies its independent exact publication contract
+  // and actual packed paths, so a source-only link cannot pass this command.
+  const { spawnSync } = require("node:child_process");
+  const result = spawnSync(process.execPath, [path.join(__dirname, "validate-package.js")], { stdio: "inherit" });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}

package/scripts/validate-package.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const { gunzipSync } = require("node:zlib");
+const { TextDecoder } = require("node:util");
+const { resolveNpmCommand } = require("./lib/npm-command.js");
+const { validateDocs } = require("./validate-docs.js");
+
+const root = path.resolve(__dirname, "..");
+const issues = [];
+
+// Keep the publication contract independent of directory contents and user state.
+const skillAssets = {
+  "add-feature": [],
+  "brainstorm-api": ["assets/api.template.md"],
+  "brainstorm-architecture": ["assets/architecture.template.md"],
+  "brainstorm-prd": ["assets/PRD.template.md"],
+  "brainstorm-rules": ["assets/rules.template.md"],
+  "brainstorm-schema": ["assets/schema.template.md"],
+  "brainstorm-styleguide": ["assets/StyleGuide.template.md"],
+  "brainstorm-task": ["assets/Task.template.md"],
+  "bug-fix": ["assets/bug-log.template.md"],
+  "code-review": ["references/review-checklist.md"],
+  developer: [
+    "references/close-phase.md",
+    "references/execute-task.md",
+    "references/onboarding.md",
+  ],
+  help: [],
+  meet: [],
+  "quick-dev": [],
+  "release-readiness": [],
+  "setup-macca-method": [],
+  "spec-audit": [],
+  "spec-compliance": [],
+  "spec-init": [],
+};
+const sharedReferences = [
+  "additional-skills", "brainstorm-session", "config-mutation", "finding-format",
+  "fix-mode", "human-loop", "implementation-principles", "invocation-policy",
+  "language-config", "interaction-contract", "output-ownership", "personas", "planning-principles", "runtime-config",
+  "scope-delta", "scope-rules", "skill-catalog", "workspace-safety",
+];
+const requiredFiles = new Set([
+  "package.json",
+  "README.md",
+  "CHANGELOG.md",
+  "docs/workflows.md",
+  "docs/configuration.md",
+  "docs/troubleshooting.md",
+  "LICENSE",
+  "flow.webp",
+  "image-macca-method.webp",
+  "bin/macca-method.js",
+  ".agents/legacy-payloads.json",
+  ".agents/macca-lock.json",
+  ".agents/macca-managed-skills.txt",
+  ...Object.entries(skillAssets).flatMap(([name, assets]) =>
+    ["SKILL.md", ...assets].map((file) => `.agents/skills/${name}/${file}`),
+  ),
+  ...sharedReferences.map((name) => `.agents/skills/_shared/references/${name}.md`),
+  ".agents/skills/_shared/scripts/validate-skills.py",
+  ".agents/skills/_shared/scripts/config-validator.js",
+  ".agents/skills/_shared/scripts/config-file.js",
+  ".agents/skills/_shared/scripts/read-preferences.js",
+  "scripts/lib/npm-command.js",
+  ...[
+    "run-skill-validator", "test-install", "test-installer-safety",
+    "test-package-safety", "test-upgrade-legacy", "validate-package",
+    "validate-skill-behavior", "validate-docs", "test-config", "test-preferences", "test-cli-setup", "test-npm-command",
+  ].map((name) => `scripts/${name}.js`),
+]);
+
+function sorted(values) {
+  return [...values].sort();
+}
+
+function readArchive(tarballPath) {
+  // Deliberately bounded to npm's regular-file ustar/local-PAX payloads. No
+  // extraction, links, global overrides, GNU extensions, or candidate execution.
+  const fail = (message) => { throw new Error(`Invalid package archive: ${message}`); };
+  const decode = (bytes) => new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const text = (bytes) => {
+    const end = bytes.indexOf(0);
+    if (end !== -1 && bytes.subarray(end).some((byte) => byte !== 0)) {
+      fail("ambiguous tar string field");
+    }
+    return decode(end === -1 ? bytes : bytes.subarray(0, end));
+  };
+  const octal = (bytes) => {
+    const value = decode(bytes).replace(/\0+$/, "").trim();
+    if (!/^[0-7]+$/.test(value)) fail("unsupported tar numeric field");
+    const result = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(result)) fail("tar numeric field overflow");
+    return result;
+  };
+  const metadataPaths = new Set([
+    "package.json", ".agents/macca-lock.json", ".agents/macca-managed-skills.txt",
+  ]);
+  if (fs.statSync(tarballPath).size > 16 * 1024 * 1024) fail("compressed size exceeds 16 MiB");
+  const tar = gunzipSync(fs.readFileSync(tarballPath), { maxOutputLength: 32 * 1024 * 1024 });
+  if (tar.length % 512 !== 0) fail("truncated tar block");
+  const files = [];
+  const metadata = new Map();
+  const seen = new Set();
+  let pax = null;
+  let offset = 0;
+  let entries = 0;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) {
+      if (pax || offset + 1024 > tar.length || tar.subarray(offset).some((byte) => byte !== 0)) {
+        fail("ambiguous or incomplete tar terminator");
+      }
+      return { files, metadata };
+    }
+    if (++entries > 4096) fail("too many tar entries");
+    const checksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+    // Checksum fields conventionally end in NUL followed by a space.
+    const storedChecksum = decode(header.subarray(148, 156)).replace(/[\0 ]+$/, "");
+    if (!/^[0-7]+$/.test(storedChecksum) || Number.parseInt(storedChecksum, 8) !== checksum) {
+      fail("tar checksum mismatch");
+    }
+    if (text(header.subarray(257, 263)) !== "ustar" || decode(header.subarray(263, 265)) !== "00") {
+      fail("unsupported tar format");
+    }
+    const size = octal(header.subarray(124, 136));
+    const bodyStart = offset + 512;
+    offset = bodyStart + Math.ceil(size / 512) * 512;
+    if (offset > tar.length) fail("truncated tar entry");
+    const body = tar.subarray(bodyStart, bodyStart + size);
+    const type = header[156];
+    if (type === 120) { // Local PAX extended header.
+      if (pax || size > 64 * 1024) fail("ambiguous or oversized PAX header");
+      pax = new Map();
+      let cursor = 0;
+      while (cursor < body.length) {
+        const space = body.indexOf(32, cursor);
+        if (space === -1) fail("malformed PAX length");
+        const lengthText = decode(body.subarray(cursor, space));
+        const length = Number(lengthText);
+        if (!/^[1-9][0-9]*$/.test(lengthText) || !Number.isSafeInteger(length) ||
+            length <= space - cursor + 1 || cursor + length > body.length || body[cursor + length - 1] !== 10) {
+          fail("malformed PAX record");
+        }
+        const record = decode(body.subarray(space + 1, cursor + length - 1));
+        const equal = record.indexOf("=");
+        const key = record.slice(0, equal);
+        if (equal < 1 || pax.has(key) || ![
+          "path", "size", "mtime", "atime", "ctime", "uid", "gid", "uname", "gname",
+          "SCHILY.dev", "SCHILY.ino", "SCHILY.nlink",
+        ].includes(key) || /[\0\r\n]/.test(record)) fail("unsupported or ambiguous PAX attribute");
+        pax.set(key, record.slice(equal + 1));
+        cursor += length;
+      }
+      continue;
+    }
+    if (type !== 0 && type !== 48) fail("unsupported tar entry type");
+    if (text(header.subarray(157, 257))) fail("regular file has a link target");
+    if (pax?.has("size") && pax.get("size") !== String(size)) fail("ambiguous PAX size");
+    const prefix = text(header.subarray(345, 500));
+    const name = text(header.subarray(0, 100));
+    const fullPath = pax?.get("path") ?? (prefix ? `${prefix}/${name}` : name);
+    pax = null;
+    if (!fullPath.startsWith("package/") || fullPath.includes("\\") ||
+        fullPath.split("/").some((part) => !part || part === "." || part === "..")) {
+      fail("non-canonical package path");
+    }
+    const relative = fullPath.slice("package/".length);
+    if (seen.has(relative)) fail("duplicate package path");
+    seen.add(relative);
+    files.push({ path: relative });
+    if (metadataPaths.has(relative)) {
+      if (size > 256 * 1024) fail("metadata exceeds 256 KiB");
+      metadata.set(relative, decode(body));
+    }
+  }
+  fail("missing tar terminator");
+}
+
+const args = process.argv.slice(2);
+if (args.length > 1 || (args.length === 1 && !fs.statSync(path.resolve(args[0])).isFile())) {
+  throw new Error("Usage: node scripts/validate-package.js [local-tarball.tgz]");
+}
+const expectedPackage = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+const archive = args.length ? readArchive(path.resolve(args[0])) : null;
+function readMetadata(relative) {
+  if (!archive) return fs.readFileSync(path.join(root, relative), "utf8");
+  if (!archive.metadata.has(relative)) throw new Error(`published package is missing ${relative}`);
+  return archive.metadata.get(relative);
+}
+const packageJson = archive ? JSON.parse(readMetadata("package.json")) : expectedPackage;
+const lock = JSON.parse(readMetadata(".agents/macca-lock.json"));
+const manifestSkills = readMetadata(".agents/macca-managed-skills.txt")
+  .split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+const packageFiles = Array.isArray(packageJson.files) ? packageJson.files : [];
+
+if (packageFiles.includes(".agents/")) {
+  issues.push("package files must not include the broad .agents/ directory");
+}
+for (const file of [
+  "docs/workflows.md", "docs/configuration.md", "docs/troubleshooting.md", "scripts/validate-docs.js",
+  "CHANGELOG.md", ".agents/skills/_shared/scripts/config-validator.js",
+  ".agents/skills/_shared/scripts/read-preferences.js", "scripts/test-preferences.js",
+]) {
+  if (!packageFiles.includes(file)) issues.push(`package files must explicitly include ${file}`);
+}
+if (packageFiles.some((file) => /^\/?docs\/?$/.test(file) || /^\/?docs\/.*[*?\[\]{}]/.test(file))) {
+  issues.push("package files must not include a broad docs directory or glob");
+}
+
+if (lock.version !== expectedPackage.version) {
+  issues.push(
+    `package/lock version mismatch: package=${expectedPackage.version} lock=${lock.version}`,
+  );
+}
+
+if (!Array.isArray(lock.skills) || JSON.stringify(sorted(lock.skills)) !== JSON.stringify(sorted(manifestSkills))) {
+  issues.push("macca-lock.json skills do not match macca-managed-skills.txt");
+}
+
+if (
+  JSON.stringify(sorted(manifestSkills)) !==
+  JSON.stringify(sorted(["_shared", ...Object.keys(skillAssets)]))
+) {
+  issues.push("managed skills do not match the official package contract");
+}
+
+function listPackageFiles() {
+  // Disable lifecycle hooks so validation cannot recursively invoke itself.
+  const npm = resolveNpmCommand(["pack", root, "--dry-run", "--json", "--ignore-scripts"]);
+  return JSON.parse(execFileSync(npm.command, npm.args, {
+    cwd: root,
+    encoding: "utf8",
+    shell: false,
+    maxBuffer: 10 * 1024 * 1024,
+  }));
+}
+
+const packageList = archive ? [{ ...packageJson, files: archive.files }] : listPackageFiles();
+if (!Array.isArray(packageList) || packageList.length !== 1 || !Array.isArray(packageList[0].files)) {
+  throw new Error("npm pack did not return exactly one package file listing");
+}
+const packed = packageList[0];
+const files = packed.files.map((entry) => entry.path);
+const fileSet = new Set(files);
+
+if (packed.name !== expectedPackage.name || packed.version !== expectedPackage.version) {
+  issues.push("tarball name/version do not match package.json");
+}
+if (fileSet.size !== files.length) {
+  issues.push("published package contains duplicate paths");
+}
+for (const file of files) {
+  if (!requiredFiles.has(file)) {
+    issues.push(`published package includes unauthorized file ${file}`);
+  }
+}
+
+for (const requiredFile of requiredFiles) {
+  if (!fileSet.has(requiredFile)) {
+    issues.push(`published package is missing ${requiredFile}`);
+  }
+}
+
+// Source links must target both a required publication file and the actual
+// pack listing. Candidate archives remain passive: never execute their code.
+if (!archive) {
+  issues.push(...validateDocs(root, new Set([...requiredFiles].filter((file) => fileSet.has(file)))));
+}
+
+if (issues.length > 0) {
+  process.stderr.write(
+    `Package contract findings:\n${issues.map((issue) => `- ${issue}`).join("\n")}\n`,
+  );
+  process.exit(1);
+}
+
+process.stdout.write(
+  `OK: package metadata and ${files.length} tarball files validated${archive ? "" : "; README and 3 guides have valid packaged links/anchors"}\n`,
+);