rankforge 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Skinner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the Software), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# rankforge
+
+Deterministic GEO/SEO readiness audits for websites and source repositories.
+
+The CLI inspects crawlability, indexability, search appearance, structured data, content answerability, entity clarity, optional performance imports, and repository audit evidence. It reports readiness by default. Measured ranking or AI-answer visibility requires supplied Search Console, SERP, or AI-answer evidence; Lighthouse exports can add performance measurements.
+
+## Install
+
+```bash
+npm install -g rankforge
+```
+
+Playwright is optional. Install it in projects where rendered page evidence is needed.
+
+## Usage
+
+```bash
+rankforge --help
+rankforge audit https://example.com --mode full --max-pages 25 --out audit.json --markdown audit.md --html audit.html
+rankforge audit-repo ./site --static-dir dist --fail-on P1 --out repo-audit.json --markdown repo-audit.md --html repo-audit.html
+rankforge explain-rule indexability.noindex
+```
+
+Use `--security restricted` for untrusted live-site audits or hosted wrappers. Restricted mode applies guarded network and file access limits and disables local command execution.
+
+## Outputs
+
+The CLI emits versioned JSON plus optional Markdown and standalone HTML reports. Findings include stable rule IDs, severity, evidence paths, implementation-task guidance, and source citations where applicable.
+
+Readiness scores are not ranking guarantees. Treat scores and findings as deterministic implementation evidence, then combine them with measured visibility data when available.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "rankforge",
+  "version": "0.3.0",
+  "description": "Deterministic GEO/SEO readiness audit CLI for websites and source repositories.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PSkinnerTech/RankForge.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/PSkinnerTech/RankForge#readme",
+  "bugs": {
+    "url": "https://github.com/PSkinnerTech/RankForge/issues"
+  },
+  "keywords": [
+    "seo",
+    "geo",
+    "generative-engine-optimization",
+    "audit",
+    "cli",
+    "technical-seo",
+    "repository-audit"
+  ],
+  "bin": {
+    "rankforge": "src/index.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/audit-output-schema.mjs

@@ -0,0 +1,88 @@
+export const auditOutputSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://rankforge.dev/schemas/rankforge-output.schema.json",
+  title: "RankForge Output",
+  type: "object",
+  required: [
+    "schemaVersion",
+    "toolVersion",
+    "run",
+    "site",
+    "pages",
+    "integrations",
+    "scores",
+    "findings",
+    "evidenceGaps",
+    "sources",
+  ],
+  additionalProperties: true,
+  properties: {
+    schemaVersion: { type: "string" },
+    toolVersion: { type: "string" },
+    run: { type: "object" },
+    site: { type: "object" },
+    pages: { type: "array" },
+    integrations: { type: "object" },
+    scores: { type: "object" },
+    findings: { type: "array" },
+    evidenceGaps: { type: "array" },
+    sources: { type: "array" },
+    repo: { type: "object" },
+  },
+};
+
+const requiredTopLevelFields = [
+  "schemaVersion",
+  "toolVersion",
+  "run",
+  "site",
+  "pages",
+  "integrations",
+  "scores",
+  "findings",
+  "evidenceGaps",
+  "sources",
+];
+
+const requiredFindingFields = [
+  "ruleId",
+  "title",
+  "severity",
+  "dimension",
+  "affectedUrls",
+  "evidence",
+  "impact",
+  "recommendation",
+  "owner",
+  "effort",
+  "confidence",
+  "sources",
+];
+
+export const validateAuditOutput = (audit) => {
+  const errors = [];
+
+  if (!audit || typeof audit !== "object" || Array.isArray(audit)) {
+    return { ok: false, errors: ["audit output must be an object"] };
+  }
+
+  for (const field of requiredTopLevelFields) {
+    if (!(field in audit)) errors.push(`${field} is required`);
+  }
+
+  if ("pages" in audit && !Array.isArray(audit.pages)) errors.push("pages must be an array");
+  if ("repo" in audit && (!audit.repo || typeof audit.repo !== "object" || Array.isArray(audit.repo))) {
+    errors.push("repo must be an object");
+  }
+  if ("findings" in audit && !Array.isArray(audit.findings)) {
+    errors.push("findings must be an array");
+  } else {
+    for (const [index, finding] of (audit.findings || []).entries()) {
+      for (const field of requiredFindingFields) {
+        if (!(field in finding)) errors.push(`findings[${index}].${field} is required`);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+};

package/src/audit.mjs

@@ -0,0 +1,202 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { crawlSite } from "./crawl.mjs";
+import { readTextFileLimited, resolveLimits } from "./io-guards.mjs";
+import { readIntegrations } from "./integrations.mjs";
+import { evaluatePerformance } from "./performance.mjs";
+import { evaluatePage, scoreFindings } from "./rule-engine.mjs";
+import { evaluateSite } from "./site-rule-engine.mjs";
+import { collectSnapshot } from "./snapshot.mjs";
+import { isHttpUrl } from "./url-utils.mjs";
+
+const toolVersion = "0.3.0";
+
+const readSourceMap = () => {
+  const candidates = [
+    new URL("./source-map.json", import.meta.url),
+    new URL("../../../skill/rankforge/source-map.json", import.meta.url),
+  ];
+
+  for (const file of candidates) {
+    try {
+      const sourceMap = JSON.parse(fs.readFileSync(file, "utf8"));
+      return Object.entries(sourceMap).map(([id, url]) => ({ id, url }));
+    } catch {
+      // Try the next source-map location.
+    }
+  }
+
+  return [];
+};
+
+const originFor = (target) => {
+  try {
+    return new URL(target).origin;
+  } catch {
+    return null;
+  }
+};
+
+const stableValue = (value) => {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return typeof value === "function" ? undefined : value;
+
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, stableValue(value[key])])
+      .filter(([, item]) => item !== undefined),
+  );
+};
+
+const configHash = (config) => crypto.createHash("sha256").update(JSON.stringify(stableValue(config))).digest("hex");
+
+const crawlSettings = (config) => ({
+  mode: config.crawl?.mode || "single",
+  maxPages: config.crawl?.maxPages ?? config.maxPages ?? null,
+  maxDepth: config.crawl?.maxDepth ?? config.maxDepth ?? null,
+});
+
+const readUrlList = (config) => {
+  const normalizeEntries = (entries, baseDir) =>
+    entries
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"))
+      .map((line) => {
+        if (isHttpUrl(line)) return line;
+        if (path.isAbsolute(line) && fs.existsSync(line)) return line;
+        if (isHttpUrl(config.target)) return new URL(line, config.target).href;
+        if (path.isAbsolute(line)) return line;
+        return path.resolve(baseDir, line);
+      });
+
+  if (Array.isArray(config.urlListEntries)) {
+    return normalizeEntries(
+      config.urlListEntries.map((entry) => String(entry)),
+      process.cwd(),
+    );
+  }
+  if (!config.urlList) return [];
+  const baseDir = path.dirname(config.urlList);
+  const limits = resolveLimits(config.limits);
+  return normalizeEntries(
+    readTextFileLimited(config.urlList, {
+      security: config.security,
+      allowRestricted: true,
+      limits,
+      maxBytes: limits.maxFileBytes,
+    }).split(/\r?\n/),
+    baseDir,
+  );
+};
+
+const collectUrlList = async (config) => {
+  const maxPages = config.crawl?.maxPages ?? config.maxPages ?? 50;
+  const urls = readUrlList(config).slice(0, maxPages);
+  const pages = [];
+
+  for (const url of urls) {
+    pages.push(
+      await collectSnapshot(url, {
+        render: config.render?.mode,
+        renderer: config.renderer,
+        security: config.security,
+        limits: config.limits,
+      }),
+    );
+  }
+
+  return { pages, skipped: [], robots: null, sitemaps: [] };
+};
+
+export const runAudit = async (config) => {
+  if (!config?.target) throw new Error("target is required");
+
+  const startedAt = new Date().toISOString();
+  const settings = crawlSettings(config);
+  const shouldCrawl = isHttpUrl(config.target) && (settings.mode === "full" || settings.mode === "sample");
+  const hasUrlList = config.urlList || Array.isArray(config.urlListEntries);
+  const crawlResult = hasUrlList
+    ? await collectUrlList(config)
+    : shouldCrawl
+      ? await crawlSite(config)
+      : {
+          pages: [
+            await collectSnapshot(config.target, {
+              render: config.render?.mode,
+              renderer: config.renderer,
+              security: config.security,
+              limits: config.limits,
+            }),
+          ],
+          skipped: [],
+          robots: null,
+          sitemaps: [],
+        };
+  const endedAt = new Date().toISOString();
+  const pages = crawlResult.pages;
+  const sitemapUrls = (crawlResult.sitemaps || []).flatMap((sitemap) => sitemap.parsed?.urls || []);
+  const integrations = readIntegrations(config.integrations, { security: config.security, limits: config.limits });
+  const hasRankingEvidence = Boolean(
+    integrations.searchConsole?.rows?.length || integrations.serp?.rows?.length || integrations.aiAnswers?.rows?.length,
+  );
+  const findings = [
+    ...pages.flatMap((item, index) => evaluatePage(item, index)),
+    ...evaluateSite(pages, {
+      crawled: shouldCrawl,
+      origin: originFor(pages[0]?.finalUrl || config.target),
+      sitemapUrls,
+      sitemaps: crawlResult.sitemaps,
+      skipped: crawlResult.skipped,
+    }),
+    ...evaluatePerformance(integrations.lighthouse),
+  ];
+
+  return {
+    schemaVersion: "1.0.0",
+    toolVersion,
+    run: {
+      id: `audit-${Date.now()}`,
+      startedAt,
+      endedAt,
+      target: config.target,
+      configHash: configHash(config),
+      mode: settings.mode,
+      crawl: settings,
+      render: config.render || { mode: "never" },
+      security: config.security || { mode: "local" },
+      limits: config.limits || {},
+      userAgent: "RankForge GEO SEO audit snapshot",
+      environment: {
+        node: process.version,
+        platform: process.platform,
+      },
+    },
+    site: {
+      origin: originFor(pages[0]?.finalUrl || config.target),
+      robots: crawlResult.robots,
+      sitemaps: crawlResult.sitemaps,
+      skipped: crawlResult.skipped,
+      notes: hasUrlList
+        ? ["Audit output contains supplied URL-list evidence."]
+        : shouldCrawl
+          ? ["Audit output contains bounded same-origin crawl evidence."]
+          : ["Audit output contains single-page snapshot evidence."],
+    },
+    pages,
+    integrations,
+    scores: scoreFindings(findings),
+    findings,
+    evidenceGaps: hasRankingEvidence
+      ? []
+      : [
+          {
+            id: "ranking.integrations_missing",
+            message:
+              "Measured rankings, SERP positions, and AI answer visibility require Search Console, SERP, or AI answer evidence.",
+          },
+        ],
+    sources: readSourceMap(),
+  };
+};