@sha3/code 1.0.0

package/lib/verify/readme-verifier.mjs

@@ -0,0 +1,216 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import ts from "typescript";
+
+import { README_REQUIRED_HEADINGS_BY_TEMPLATE } from "../constants.mjs";
+import { createContractIssue } from "./issue-helpers.mjs";
+import { extractPublicReadmeApi } from "./readme-public-api.mjs";
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function extractHeadingSection(readmeRaw, heading) {
+  const lines = readmeRaw.split("\n");
+  const headingIndex = lines.findIndex((line) => line.trim() === heading);
+
+  if (headingIndex === -1) {
+    return null;
+  }
+
+  const sectionLines = [];
+
+  for (const line of lines.slice(headingIndex + 1)) {
+    if (line.startsWith("## ") || line.startsWith("# ")) {
+      break;
+    }
+
+    sectionLines.push(line);
+  }
+
+  return sectionLines.join("\n");
+}
+
+function hasExportSection(readmeRaw, exportName) {
+  return readmeRaw.split("\n").some((line) => line.trim() === `### \`${exportName}\``);
+}
+
+function hasMethodSection(readmeRaw, methodName) {
+  return readmeRaw.split("\n").some((line) => line.trim().startsWith(`#### \`${methodName}`));
+}
+
+function hasPackageRootImportExample(readmeRaw, packageName) {
+  if (!packageName) {
+    return false;
+  }
+
+  return new RegExp(`from ["']${escapeRegExp(packageName)}["']`).test(readmeRaw);
+}
+
+function hasDocumentedHttpEndpoint(readmeRaw) {
+  const httpApiSection = extractHeadingSection(readmeRaw, "## HTTP API");
+
+  if (!httpApiSection) {
+    return false;
+  }
+
+  return /\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b\s+\/\S*/.test(httpApiSection);
+}
+
+function hasScaffoldLikeLanguage(readmeRaw) {
+  return /\b(?:placeholder|todo|your project|lorem ipsum|scaffold(?:ed|ing)?|generated(?:\s+from\s+code)?|template README|boilerplate)\b/i.test(readmeRaw);
+}
+
+function collectConfigKeys(configRaw, configPath) {
+  const sourceFile = ts.createSourceFile(configPath, configRaw, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const keys = [];
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) {
+      continue;
+    }
+
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "config" || !declaration.initializer) {
+        continue;
+      }
+
+      const initializer = ts.isAsExpression(declaration.initializer) ? declaration.initializer.expression : declaration.initializer;
+      if (!ts.isObjectLiteralExpression(initializer)) {
+        continue;
+      }
+
+      for (const property of initializer.properties) {
+        if (ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) {
+          keys.push(property.name.text);
+        }
+      }
+    }
+  }
+
+  return keys;
+}
+
+export async function verifyReadme(targetPath, options) {
+  const { contract, packageName, template } = options;
+  const readmePath = path.join(targetPath, "README.md");
+  const readmeRaw = await readFile(readmePath, "utf8");
+  const configPath = path.join(targetPath, "src", "config.ts");
+  const configRaw = await readFile(configPath, "utf8").catch(() => "");
+  const issues = [];
+  const requiredHeadings = README_REQUIRED_HEADINGS_BY_TEMPLATE[template] ?? [];
+
+  for (const heading of requiredHeadings) {
+    if (!readmeRaw.includes(heading)) {
+      issues.push(
+        createContractIssue(contract, {
+          ruleId: "readme-sections",
+          category: "readme",
+          relativePath: "README.md",
+          message: `missing required README heading: ${heading}`,
+        }),
+      );
+    }
+  }
+
+  const publicReadmeApi = await extractPublicReadmeApi(targetPath);
+
+  for (const exportedMember of publicReadmeApi.exports) {
+    if (!hasExportSection(readmeRaw, exportedMember.exportName)) {
+      issues.push(
+        createContractIssue(contract, {
+          ruleId: "readme-public-api",
+          category: "readme",
+          relativePath: "README.md",
+          message: `missing README section for public export: ${exportedMember.exportName}`,
+        }),
+      );
+      continue;
+    }
+
+    if (exportedMember.kind !== "class") {
+      continue;
+    }
+
+    for (const publicMethod of exportedMember.publicMethods) {
+      if (!hasMethodSection(readmeRaw, publicMethod)) {
+        issues.push(
+          createContractIssue(contract, {
+            ruleId: "readme-public-methods",
+            category: "readme",
+            relativePath: "README.md",
+            message: `missing README method documentation: ${exportedMember.exportName}.${publicMethod}()`,
+          }),
+        );
+      }
+    }
+  }
+
+  if (template === "node-lib" && !hasPackageRootImportExample(readmeRaw, packageName)) {
+    issues.push(
+      createContractIssue(contract, {
+        ruleId: "readme-usage-examples",
+        category: "readme",
+        relativePath: "README.md",
+        message: "README examples must show at least one import from the package root",
+      }),
+    );
+  }
+
+  if (template === "node-service" && !hasDocumentedHttpEndpoint(readmeRaw)) {
+    issues.push(
+      createContractIssue(contract, {
+        ruleId: "readme-http-api",
+        category: "readme",
+        relativePath: "README.md",
+        message: "README HTTP API section must document at least one endpoint with method and path",
+      }),
+    );
+  }
+
+  if (hasScaffoldLikeLanguage(readmeRaw)) {
+    issues.push(
+      createContractIssue(contract, {
+        ruleId: "readme-no-placeholder-language",
+        category: "readme",
+        relativePath: "README.md",
+        message: "README contains placeholder, scaffold-like, or generated-documentation language",
+        verificationMode: "heuristic",
+        confidence: "medium",
+        evidence: "placeholder/scaffold wording",
+      }),
+    );
+  }
+
+  const configKeys = collectConfigKeys(configRaw, configPath);
+  for (const configKey of configKeys) {
+    if (!readmeRaw.includes(configKey)) {
+      issues.push(
+        createContractIssue(contract, {
+          ruleId: "readme-config-coverage",
+          category: "readme",
+          relativePath: "README.md",
+          message: `README must document config key: ${configKey}`,
+        }),
+      );
+    }
+  }
+
+  const hasPlausibleCodeExample = /```(?:ts|bash)\n[\s\S]*?(?:npm |import |\bnode\b|\bconst\b)/.test(readmeRaw);
+  if (!hasPlausibleCodeExample) {
+    issues.push(
+      createContractIssue(contract, {
+        ruleId: "readme-runnable-examples",
+        category: "readme",
+        relativePath: "README.md",
+        message: "README must include plausible runnable command or TypeScript examples",
+        verificationMode: "heuristic",
+        confidence: "medium",
+        evidence: "missing runnable ts/bash example",
+      }),
+    );
+  }
+
+  return issues;
+}

package/lib/verify/render-json-report.mjs

@@ -0,0 +1,3 @@
+export function renderJsonReport(result) {
+  return JSON.stringify(result, null, 2);
+}

package/lib/verify/render-text-report.mjs

@@ -0,0 +1,34 @@
+function formatLocation(issue) {
+  if (!issue.relativePath) {
+    return "";
+  }
+
+  if (typeof issue.line !== "number") {
+    return issue.relativePath;
+  }
+
+  if (typeof issue.column !== "number") {
+    return `${issue.relativePath}:${issue.line}`;
+  }
+
+  return `${issue.relativePath}:${issue.line}:${issue.column}`;
+}
+
+export function renderTextReport(result) {
+  if (result.ok) {
+    const warningSuffix = result.hasWarnings ? ` (${result.summary.warningCount} warning(s), ${result.summary.auditCount} audit item(s))` : "";
+    return `standards verification passed${warningSuffix}`;
+  }
+
+  return result.issues
+    .map((issue) => {
+      const location = formatLocation(issue);
+      const mode = issue.verificationMode ? `/${issue.verificationMode}` : "";
+      const severity = issue.severity ? `${issue.severity.toUpperCase()} ` : "";
+      const evidence = issue.evidence ? ` (${issue.evidence})` : "";
+      return location.length > 0
+        ? `- ${severity}[${issue.ruleId}${mode}] ${location}: ${issue.message}${evidence}`
+        : `- ${severity}[${issue.ruleId}${mode}] ${issue.message}${evidence}`;
+    })
+    .join("\n");
+}

package/lib/verify/source-analysis.mjs

@@ -0,0 +1,126 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import ts from "typescript";
+
+import { listRelativeFiles } from "../project/template-resolution.mjs";
+import { isFileSelected } from "./issue-helpers.mjs";
+
+export async function loadProjectSourceFiles(targetPath, options = {}) {
+  const files = await listRelativeFiles(targetPath);
+  const sourceFiles = [];
+
+  for (const relativePath of files) {
+    if ((!relativePath.startsWith("src/") && !relativePath.startsWith("test/")) || !relativePath.endsWith(".ts") || relativePath.endsWith(".d.ts")) {
+      continue;
+    }
+
+    if (!isFileSelected(options.files, relativePath)) {
+      continue;
+    }
+
+    const absolutePath = path.join(targetPath, relativePath);
+    const raw = await readFile(absolutePath, "utf8");
+    const ast = ts.createSourceFile(absolutePath, raw, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    sourceFiles.push({ relativePath, absolutePath, raw, ast });
+  }
+
+  return sourceFiles;
+}
+
+export async function loadProjectAnalysisContext(targetPath, options = {}) {
+  const sourceFiles = await loadProjectSourceFiles(targetPath, options);
+  const absolutePaths = sourceFiles.map((file) => file.absolutePath);
+  const compilerOptions = {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    allowJs: false,
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+  };
+  const program = ts.createProgram(absolutePaths, compilerOptions);
+  const checker = program.getTypeChecker();
+  const sourceFilesByPath = new Map();
+  const sourceFilesByRelativePath = new Map();
+
+  for (const file of sourceFiles) {
+    const programSourceFile = program.getSourceFile(file.absolutePath);
+    const enriched = {
+      ...file,
+      ast: programSourceFile ?? file.ast,
+      featureName: getFeatureName(file.relativePath),
+      isRootSourceFile: isRootSourceFile(file.relativePath),
+    };
+    sourceFilesByPath.set(file.absolutePath, enriched);
+    sourceFilesByRelativePath.set(file.relativePath, enriched);
+  }
+
+  return { targetPath, compilerOptions, sourceFiles: [...sourceFilesByRelativePath.values()], sourceFilesByPath, sourceFilesByRelativePath, program, checker };
+}
+
+export function isExportedClass(node) {
+  return ts.isClassDeclaration(node) && Array.isArray(node.modifiers) && node.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+
+export function visitNodes(node, visitor) {
+  visitor(node);
+  ts.forEachChild(node, (child) => visitNodes(child, visitor));
+}
+
+export function visitNonNestedStatements(node, visitor) {
+  ts.forEachChild(node, (child) => {
+    if (
+      ts.isFunctionDeclaration(child) ||
+      ts.isFunctionExpression(child) ||
+      ts.isArrowFunction(child) ||
+      ts.isMethodDeclaration(child) ||
+      ts.isConstructorDeclaration(child)
+    ) {
+      return;
+    }
+
+    visitor(child);
+    visitNonNestedStatements(child, visitor);
+  });
+}
+
+export function getIdentifierText(name) {
+  return ts.isIdentifier(name) ? name.text : null;
+}
+
+export function getFeatureName(relativePath) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+
+  if (!normalizedPath.startsWith("src/")) {
+    return null;
+  }
+
+  const segments = normalizedPath.split("/");
+  return segments.length >= 3 ? segments[1] : null;
+}
+
+export function isRootSourceFile(relativePath) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+  return normalizedPath.startsWith("src/") && normalizedPath.split("/").length === 2;
+}
+
+export function resolveImportRelativePath(relativePath, specifier) {
+  if (!specifier.startsWith(".")) {
+    return null;
+  }
+
+  const normalizedSourceDir = path.posix.dirname(relativePath.split(path.sep).join("/"));
+  const resolved = path.posix.normalize(path.posix.join(normalizedSourceDir, specifier));
+  return resolved.endsWith(".ts") ? resolved : `${resolved}.ts`;
+}
+
+export function getLineAndColumn(sourceFile, position) {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(position);
+  return { line: line + 1, column: character + 1 };
+}
+
+export function getNodeTextSlice(sourceFile, node) {
+  return sourceFile.text.slice(node.getStart(sourceFile), node.getEnd());
+}