@cdxgen/cdxgen 0.0.1 → 13.0.1

package/lib/parsers/gitAiNotes.js

@@ -0,0 +1,233 @@
+/**
+ * Tolerant parser for git-ai notes.
+ *
+ * Supports three shapes, all degrading gracefully (never throws):
+ *  1. The real git-ai `authorship/*` schema: per-file attribution blocks
+ *     followed by a `---` separator and a JSON metadata block carrying
+ *     `sessions` (each with an `agent_id` describing the AI tool/model).
+ *  2. A flat JSON object `{ agent, model, session, prompt, lines, ranges }`.
+ *  3. Line-oriented `key: value` / `key = value` text.
+ *
+ * @param {string} raw Raw git note content
+ * @returns {Object} Extracted fields { agent, model, session, prompt, lines, ranges, sessions, prompts, agents, models, aiAttributionCount }
+ */
+export function parseGitAiNote(raw) {
+  const result = {
+    agent: "",
+    model: "",
+    session: "",
+    prompt: "",
+    lines: [],
+    ranges: [],
+    sessions: {},
+    prompts: {},
+    agents: [],
+    models: [],
+    aiAttributionCount: 0,
+  };
+
+  if (!raw || typeof raw !== "string") {
+    return result;
+  }
+
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return result;
+  }
+
+  // git-ai `authorship/*` notes: optional per-file attribution section, then a
+  // line that is exactly `---`, then a JSON metadata block. Detect and parse
+  // this first because the note as a whole is not valid JSON.
+  const authorship = tryParseAuthorshipNote(trimmed);
+  if (authorship) {
+    return authorship;
+  }
+
+  // Flat JSON note.
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object") {
+      if (parsed.agent) result.agent = String(parsed.agent);
+      if (parsed.model) result.model = String(parsed.model);
+      if (parsed.session) result.session = String(parsed.session);
+      if (parsed.prompt) result.prompt = String(parsed.prompt);
+      if (Array.isArray(parsed.lines)) {
+        result.lines = parsed.lines;
+      }
+      if (Array.isArray(parsed.ranges)) {
+        result.ranges = parsed.ranges;
+      }
+      result.aiAttributionCount = result.ranges.length + result.lines.length;
+      return result;
+    }
+  } catch {
+    // Ignore JSON error, fall back to line parsing
+  }
+
+  // Fallback: line-oriented text parsing
+  for (const line of trimmed.split("\n")) {
+    const lineTrim = line.trim();
+    if (!lineTrim || lineTrim.startsWith("#")) {
+      continue;
+    }
+    const match = lineTrim.match(/^([a-zA-Z0-9_-]+)\s*[:=]\s*(.*)$/);
+    if (match) {
+      const key = match[1].toLowerCase();
+      const val = match[2].trim();
+      if (key === "agent") result.agent = val;
+      else if (key === "model") result.model = val;
+      else if (key === "session") result.session = val;
+      else if (key === "prompt") result.prompt = val;
+      else if (key === "lines" || key === "ranges") {
+        try {
+          if (val.startsWith("[") && val.endsWith("]")) {
+            result[key] = JSON.parse(val);
+          } else {
+            result[key] = val
+              .split(",")
+              .map((v) => v.trim())
+              .filter(Boolean);
+          }
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  result.aiAttributionCount = result.ranges.length + result.lines.length;
+
+  return result;
+}
+
+/**
+ * Parse a git-ai `authorship/*` note per the Git AI Standard v3.0.0. Returns
+ * null if the note is not in that format so callers can fall back to other
+ * parsers.
+ *
+ * The note is `<attestation-section>` + a line that is exactly `---` +
+ * `<metadata JSON>`. Attestation entries are `  <key> <ranges>` where the key
+ * routes by prefix (spec section 1.2.3.1):
+ *   - `s_<hex>::t_<hex>` -> AI session; session id (before `::`) in `sessions`.
+ *   - `h_<hex>`          -> KNOWN HUMAN (`humans`); NOT AI, ignored here.
+ *   - `<16hex>` (no prefix) -> legacy AI session in `prompts`.
+ *
+ * @param {string} trimmed Trimmed raw note content
+ * @returns {Object|null} Parsed fields, or null when not an authorship note
+ */
+function tryParseAuthorshipNote(trimmed) {
+  // The divider is a line containing exactly `---`. Metadata-only notes (purely
+  // human commits) start with `---`; bare JSON is accepted defensively.
+  let attributionText = "";
+  let jsonText = "";
+  const sepMatch = trimmed.match(/(^|\n)---[ \t]*\r?\n/);
+  if (sepMatch) {
+    const idx = sepMatch.index + sepMatch[0].length;
+    attributionText = trimmed.slice(0, sepMatch.index);
+    jsonText = trimmed.slice(idx).trim();
+  } else if (trimmed.startsWith("{")) {
+    jsonText = trimmed;
+  } else {
+    return null;
+  }
+
+  let meta;
+  try {
+    meta = JSON.parse(jsonText);
+  } catch {
+    return null;
+  }
+  if (
+    !meta ||
+    typeof meta !== "object" ||
+    typeof meta.schema_version !== "string" ||
+    !meta.schema_version.startsWith("authorship")
+  ) {
+    return null;
+  }
+
+  const result = {
+    agent: "",
+    model: "",
+    session: "",
+    prompt: "",
+    lines: [],
+    ranges: [],
+    sessions: {},
+    prompts: {},
+    agents: [],
+    models: [],
+    aiAttributionCount: 0,
+  };
+
+  const asObject = (value) => (value && typeof value === "object" ? value : {});
+  const metaSessions = asObject(meta.sessions); // s_<hex> -> { agent_id, ... }
+  const metaPrompts = asObject(meta.prompts); // legacy <16hex> -> { agent_id, ... }
+  result.sessions = metaSessions;
+  result.prompts = metaPrompts;
+
+  // Collect all unique agent tool names and model names from sessions and
+  // prompts. Also record the first AI agent as the primary attribution key.
+  const agentSet = new Set();
+  const modelSet = new Set();
+  const collectAgent = (key, record) => {
+    const agentObj = record?.agent_id;
+    if (agentObj) {
+      const tool = agentObj.tool ? String(agentObj.tool) : "";
+      const model = agentObj.model ? String(agentObj.model) : "";
+      if (tool || model) {
+        if (tool) agentSet.add(tool);
+        if (model) modelSet.add(model);
+        if (!result.agent) {
+          result.agent = tool;
+          result.model = model;
+          result.session = key;
+        }
+      }
+    }
+  };
+  for (const [sid, sess] of Object.entries(metaSessions)) {
+    collectAgent(sid, sess);
+  }
+  for (const [pid, prompt] of Object.entries(metaPrompts)) {
+    collectAgent(pid, prompt);
+  }
+  result.agents = [...agentSet].sort();
+  result.models = [...modelSet].sort();
+
+  /**
+   * Resolve an attestation key to whether it denotes AI authorship.
+   * @param {string} key attestation key
+   * @returns {boolean} true when the key maps to an AI session/prompt
+   */
+  const isAiKey = (key) => {
+    if (key.startsWith("h_")) {
+      return false; // known human
+    }
+    if (key.startsWith("s_")) {
+      const sessionId = key.split("::")[0];
+      return Object.hasOwn(metaSessions, sessionId);
+    }
+    // Legacy bare-hex key routes to prompts.
+    return Object.hasOwn(metaPrompts, key);
+  };
+
+  // Attestation entries are indented `  <key> <ranges>`; ranges never contain
+  // spaces. File-path lines (unindented) and anything else are ignored here.
+  for (const rawLine of attributionText.split("\n")) {
+    const attr = rawLine.match(/^\s+(\S+)[ \t]+(\S+)\s*$/);
+    if (!attr || !isAiKey(attr[1])) {
+      continue;
+    }
+    for (const part of attr[2].split(",")) {
+      const token = part.trim();
+      if (token) {
+        result.ranges.push(token);
+      }
+    }
+  }
+
+  result.aiAttributionCount = result.ranges.length;
+
+  return result;
+}

package/lib/parsers/gitmodules.js

@@ -0,0 +1,239 @@
+/**
+ * Pure parser for `.gitmodules` (git config INI) and a URL→purl coordinate helper.
+ *
+ * The file format is git-config INI:
+ *
+ * ```
+ * [submodule "name"]
+ *     path = third_party/foo
+ *     url = https://github.com/org/foo.git
+ *     branch = main
+ * ```
+ *
+ * Submodule URLs are frequently *relative* (`../dep`, `../../org/dep`). Such a
+ * URL is meaningless until resolved against the origin remote. The
+ * {@link resolveSubmoduleUrl} helper takes the origin URL as an argument
+ * (rather than discovering it) so this module stays layer 1 — no git, no fs.
+ *
+ * Purl coordinates are produced here as plain data; the purl *string* is built
+ * by the layer-3 resolver via `tryBuildPurl`, because cdx-purl lives in layer 2
+ * and a layer-1 parser may not reach it.
+ */
+
+const SUBMODULE_HEADER = /^\s*\[submodule\s+"(.*)"\s*\]\s*$/;
+
+/**
+ * Parse `.gitmodules` text into an ordered list of submodule descriptors.
+ *
+ * @param {string} text Raw `.gitmodules` contents
+ * @returns {{ name: string, path?: string, url?: string, branch?: string }[]} Submodules in file order
+ */
+export function parseGitmodules(text) {
+  const submodules = [];
+  if (!text || typeof text !== "string") {
+    return submodules;
+  }
+  let current = null;
+  for (const rawLine of text.split(/\r\n|\r|\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) {
+      continue;
+    }
+    const header = line.match(SUBMODULE_HEADER);
+    if (header) {
+      current = { name: header[1] };
+      submodules.push(current);
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) {
+      continue;
+    }
+    const key = line.slice(0, eqIndex).trim();
+    const value = line.slice(eqIndex + 1).trim();
+    if (!key) {
+      continue;
+    }
+    if (key === "path") {
+      current.path = value;
+    } else if (key === "url") {
+      current.url = value;
+    } else if (key === "branch") {
+      current.branch = value;
+    }
+  }
+  return submodules;
+}
+
+/**
+ * Parse a git remote URL into an origin descriptor.
+ *
+ * Supports https, the `git@host:owner/repo` SSH shorthand, and
+ * `ssh://git@host/owner/repo` URLs.
+ *
+ * @param {string} url Origin remote URL
+ * @returns {{ scheme: string, host?: string, owner?: string, name?: string, baseUrl?: string } | null}
+ */
+export function parseGitRemoteUrl(url) {
+  if (!url || typeof url !== "string") {
+    return null;
+  }
+  if (url.startsWith("http://") || url.startsWith("https://")) {
+    const parsed = safeWebUrl(url);
+    if (!parsed) {
+      return null;
+    }
+    return parsed;
+  }
+  if (url.startsWith("git@")) {
+    const colon = url.indexOf(":");
+    if (colon === -1) {
+      return null;
+    }
+    const host = url.slice(0, colon).split("@")[1];
+    const pathPart = url.slice(colon + 1).replace(/\.git$/, "");
+    const segments = pathPart.split("/").filter(Boolean);
+    const name = segments.pop();
+    const owner = segments.join("/");
+    if (!host || !name) {
+      return null;
+    }
+    return {
+      scheme: "ssh",
+      host,
+      owner,
+      name,
+      baseUrl: `https://${host}/${owner}`,
+    };
+  }
+  if (url.startsWith("ssh://")) {
+    const noScheme = url.slice("ssh://".length);
+    const at = noScheme.indexOf("@");
+    const hostStart = at === -1 ? 0 : at + 1;
+    const rest = noScheme.slice(hostStart);
+    const slash = rest.indexOf("/");
+    if (slash === -1) {
+      return null;
+    }
+    const host = rest.slice(0, slash);
+    const pathPart = rest.slice(slash + 1).replace(/\.git$/, "");
+    const segments = pathPart.split("/").filter(Boolean);
+    const name = segments.pop();
+    const owner = segments.join("/");
+    if (!host || !name) {
+      return null;
+    }
+    return {
+      scheme: "ssh",
+      host,
+      owner,
+      name,
+      baseUrl: `https://${host}/${owner}`,
+    };
+  }
+  return null;
+}
+
+function safeWebUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const pathnameParts = parsed.pathname.split("/").filter(Boolean);
+    if (pathnameParts[pathnameParts.length - 1] === "") {
+      pathnameParts.pop();
+    }
+    const name = pathnameParts.pop()?.replace(/\.git$/, "");
+    const owner = pathnameParts.join("/");
+    if (!name) {
+      return null;
+    }
+    return {
+      scheme: parsed.protocol.slice(0, -1),
+      host: parsed.hostname,
+      owner,
+      name,
+      baseUrl: `https://${parsed.hostname}/${owner}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a submodule URL that may be relative against the origin remote.
+ *
+ * Git treats the superproject URL as a *directory* rather than a file, so
+ * `../bar` against `https://example.com/repositories/foo` resolves to
+ * `https://example.com/repositories/bar`, and `./inner` resolves to
+ * `https://example.com/repositories/foo/inner`. RFC 3986 would strip the last
+ * segment first and land a level higher, so the base carries an explicit
+ * trailing slash before resolution. SSH shorthand origins (`git@host:o/root`)
+ * are normalised to `https://host/o/root` first.
+ *
+ * @param {string} submoduleUrl URL from `.gitmodules` (absolute or relative)
+ * @param {string} originUrl Origin remote URL of the containing repo
+ * @returns {string|null} Absolute URL, or null when it cannot be resolved
+ */
+export function resolveSubmoduleUrl(submoduleUrl, originUrl) {
+  if (!submoduleUrl) {
+    return null;
+  }
+  if (!submoduleUrl.startsWith(".")) {
+    return submoduleUrl;
+  }
+  const origin = parseGitRemoteUrl(originUrl);
+  if (!origin?.host) {
+    return null;
+  }
+  const originPath = [origin.owner, origin.name].filter(Boolean).join("/");
+  const base = `https://${origin.host}/${originPath}/`;
+  try {
+    const resolved = new URL(submoduleUrl, base);
+    resolved.hash = "";
+    resolved.password = "";
+    resolved.username = "";
+    return resolved.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build purl coordinates from a resolved submodule URL.
+ *
+ * GitHub remotes become `pkg:github/<owner>/<name>@<version>`; every other
+ * host becomes `pkg:generic` coordinates with a `vcs_url` qualifier, because
+ * only GitHub has a registered purl type that cdx-purl recognises.
+ *
+ * The caller (layer 3) turns these into a purl string via `tryBuildPurl`.
+ *
+ * @param {string} resolvedUrl Absolute git URL
+ * @param {string} [version] Resolved version (tag or commit SHA)
+ * @returns {{ type: string, namespace: string|null, name: string, version: string|null, qualifiers?: { vcs_url: string } } | null}
+ */
+export function submodulePurlCoordinates(resolvedUrl, version) {
+  const remote = parseGitRemoteUrl(resolvedUrl);
+  if (!remote?.name) {
+    return null;
+  }
+  if (remote.host === "github.com") {
+    // The github purl type namespaces on the owner alone. The host belongs in
+    // the type, not the namespace, so `pkg:github/google/benchmark` is the form
+    // other tools produce for the same repository.
+    return {
+      type: "github",
+      namespace: remote.owner || null,
+      name: remote.name,
+      version: version || null,
+    };
+  }
+  return {
+    type: "generic",
+    namespace: remote.owner ? `${remote.host}/${remote.owner}` : remote.host,
+    name: remote.name,
+    version: version || null,
+    qualifiers: { vcs_url: resolvedUrl },
+  };
+}