@sha3/code 1.0.0

package/lib/verify/source-rule-verifier.mjs

@@ -0,0 +1,453 @@
+import path from "node:path";
+
+import ts from "typescript";
+
+import { createVerificationIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+import { getIdentifierText, isExportedClass, loadProjectSourceFiles, visitNodes, visitNonNestedStatements } from "./source-analysis.mjs";
+
+const FORBIDDEN_IDENTIFIER_NAMES = new Set(["data", "obj", "tmp", "val", "thing", "helper", "utils", "common"]);
+const BOOLEAN_PREFIX_PATTERN = /^(is|has|can|should)[A-Z0-9_]/;
+const FEATURE_ROLE_SUFFIXES = new Set(["service", "types", "helpers", "errors", "repository", "controller", "handler", "mapper", "schema", "runtime"]);
+const ROOT_SOURCE_EXEMPTIONS = new Set(["config.ts", "index.ts", "logger.ts", "main.ts"]);
+
+function countReturnsInBody(body) {
+  let returnCount = 0;
+
+  visitNonNestedStatements(body, (node) => {
+    if (ts.isReturnStatement(node)) {
+      returnCount += 1;
+    }
+  });
+
+  return returnCount;
+}
+
+function isBooleanLikeDeclaration(node) {
+  if (node.type && node.type.kind === ts.SyntaxKind.BooleanKeyword) {
+    return true;
+  }
+
+  return node.initializer ? node.initializer.kind === ts.SyntaxKind.TrueKeyword || node.initializer.kind === ts.SyntaxKind.FalseKeyword : false;
+}
+
+const SECTION_MARKER_PATTERN = /\/\*\*\s*\n\s*\* @section\s+([a-z:]+)\s*\n\s*\*\//g;
+
+function collectSectionMarkers(raw) {
+  return [...raw.matchAll(SECTION_MARKER_PATTERN)].map((match) => ({
+    name: match[1],
+    startIndex: match.index,
+    endIndex: (match.index ?? 0) + match[0].length,
+  }));
+}
+
+function stripCommentsAndWhitespace(raw) {
+  return raw
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/[^\n]*/g, "")
+    .trim();
+}
+
+function findEmptySectionMarkers(raw, markers) {
+  const failures = [];
+
+  for (const [index, marker] of markers.entries()) {
+    const nextMarker = markers[index + 1];
+    const sectionBody = raw.slice(marker.endIndex, nextMarker?.startIndex ?? raw.length);
+
+    if (stripCommentsAndWhitespace(sectionBody).length === 0) {
+      failures.push(
+        createVerificationIssue({
+          ruleId: "class-section-order",
+          category: "source-rule",
+          relativePath: "",
+          message: `empty @section block must be omitted: ${marker.name}`,
+        }),
+      );
+    }
+  }
+
+  return failures;
+}
+
+function verifyClassSectionPlacement(relativePath, raw, markers, exportedClass) {
+  const classMarker = markers.find((marker) => marker.name === "class");
+
+  if (!classMarker) {
+    return [
+      createVerificationIssue({
+        ruleId: "class-section-order",
+        category: "source-rule",
+        relativePath,
+        message: "public class files must declare @section class immediately before the exported class",
+      }),
+    ];
+  }
+
+  const classStartIndex = exportedClass.getStart(exportedClass.getSourceFile());
+
+  if (classMarker.startIndex > classStartIndex) {
+    return [
+      createVerificationIssue({
+        ruleId: "class-section-order",
+        category: "source-rule",
+        relativePath,
+        message: "@section class must appear before the exported class declaration",
+      }),
+    ];
+  }
+
+  const between = raw.slice(classMarker.endIndex, classStartIndex);
+
+  return between.trim().length === 0
+    ? []
+    : [
+        createVerificationIssue({
+          ruleId: "class-section-order",
+          category: "source-rule",
+          relativePath,
+          message: "@section class must appear immediately before the exported class declaration with no intervening comments",
+        }),
+      ];
+}
+
+function verifySectionOrder(relativePath, raw, sectionOrder, exportedClass) {
+  const markers = collectSectionMarkers(raw);
+
+  if (markers.length === 0) {
+    return [
+      createVerificationIssue({
+        ruleId: "class-section-order",
+        category: "source-rule",
+        relativePath,
+        message: "public class files must include ordered @section markers",
+      }),
+    ];
+  }
+
+  const failures = [];
+  let lastIndex = -1;
+
+  for (const marker of markers) {
+    const markerIndex = sectionOrder.indexOf(marker.name);
+
+    if (markerIndex < 0) {
+      failures.push(
+        createVerificationIssue({
+          ruleId: "class-section-order",
+          category: "source-rule",
+          relativePath,
+          message: `unknown @section marker: ${marker.name}`,
+        }),
+      );
+      continue;
+    }
+
+    if (markerIndex < lastIndex) {
+      failures.push(
+        createVerificationIssue({
+          ruleId: "class-section-order",
+          category: "source-rule",
+          relativePath,
+          message: `out-of-order @section marker: ${marker.name}`,
+        }),
+      );
+    }
+
+    lastIndex = markerIndex;
+  }
+
+  for (const issue of findEmptySectionMarkers(raw, markers)) {
+    failures.push({ ...issue, relativePath });
+  }
+
+  failures.push(...verifyClassSectionPlacement(relativePath, raw, markers, exportedClass));
+
+  return failures;
+}
+
+function verifyFeatureFilename(relativePath) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+
+  if (!normalizedPath.startsWith("src/")) {
+    return [];
+  }
+
+  const segments = normalizedPath.split("/");
+  const fileName = segments.at(-1);
+
+  if (segments.length <= 2 || ROOT_SOURCE_EXEMPTIONS.has(fileName)) {
+    return [];
+  }
+
+  const roleMatch = fileName.match(/\.([a-z]+)\.ts$/);
+  if (!roleMatch || !FEATURE_ROLE_SUFFIXES.has(roleMatch[1])) {
+    return [
+      createVerificationIssue({
+        ruleId: "feature-filename-role",
+        category: "source-rule",
+        relativePath,
+        message: "feature files must include an explicit role suffix such as .service.ts, .types.ts, or .helpers.ts",
+      }),
+    ];
+  }
+
+  return [];
+}
+
+function verifyFeatureClassOnly(relativePath, ast) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+
+  if (!normalizedPath.startsWith("src/")) {
+    return [];
+  }
+
+  const segments = normalizedPath.split("/");
+  const fileName = segments.at(-1);
+
+  if (segments.length <= 2 || ROOT_SOURCE_EXEMPTIONS.has(fileName) || fileName.endsWith(".types.ts")) {
+    return [];
+  }
+
+  const exportedClasses = ast.statements.filter((statement) => isExportedClass(statement));
+
+  if (exportedClasses.length !== 1) {
+    return [
+      createVerificationIssue({
+        ruleId: "feature-class-only",
+        category: "source-rule",
+        relativePath,
+        message: "feature files must expose exactly one public class; only .types.ts files may expose non-class exports",
+      }),
+    ];
+  }
+
+  return [];
+}
+
+function verifyNoModuleFunctionsInClassFiles(relativePath, ast) {
+  const exportedClasses = ast.statements.filter((statement) => isExportedClass(statement));
+
+  if (exportedClasses.length === 0) {
+    return [];
+  }
+
+  const issues = [];
+
+  for (const statement of ast.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name) {
+      issues.push(
+        createVerificationIssue({
+          ruleId: "no-module-functions-in-class-files",
+          category: "source-rule",
+          relativePath,
+          message: `class files must not define module-scope helper functions: ${statement.name.text}`,
+        }),
+      );
+      continue;
+    }
+
+    if (!ts.isVariableStatement(statement)) {
+      continue;
+    }
+
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+        continue;
+      }
+
+      if (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)) {
+        issues.push(
+          createVerificationIssue({
+            ruleId: "no-module-functions-in-class-files",
+            category: "source-rule",
+            relativePath,
+            message: `class files must not define module-scope helper functions: ${declaration.name.text}`,
+          }),
+        );
+      }
+    }
+  }
+
+  return issues;
+}
+
+function verifyConfigImport(relativePath, node) {
+  const specifier = node.moduleSpecifier.text;
+
+  if (!specifier.startsWith(".") || !/(^|\/)config(?:\.ts)?$/.test(specifier)) {
+    return [];
+  }
+
+  const failures = [];
+  const importClause = node.importClause;
+
+  if (!specifier.endsWith("config.ts")) {
+    failures.push(
+      createVerificationIssue({
+        ruleId: "canonical-config-import",
+        category: "source-rule",
+        relativePath,
+        message: "config imports must include the .ts extension",
+      }),
+    );
+  }
+
+  if (!importClause || !importClause.name || importClause.name.text !== "config" || importClause.namedBindings) {
+    failures.push(
+      createVerificationIssue({
+        ruleId: "canonical-config-import",
+        category: "source-rule",
+        relativePath,
+        message: 'config imports must use `import config from ".../config.ts"`',
+      }),
+    );
+  }
+
+  return failures;
+}
+
+function verifyIdentifier(ruleId, relativePath, name) {
+  if (!name) {
+    return [];
+  }
+
+  return FORBIDDEN_IDENTIFIER_NAMES.has(name)
+    ? [
+        createVerificationIssue({
+          ruleId,
+          category: "source-rule",
+          relativePath,
+          message: `forbidden generic identifier: ${name}`,
+        }),
+      ]
+    : [];
+}
+
+function verifyBooleanName(relativePath, name) {
+  if (!name || BOOLEAN_PREFIX_PATTERN.test(name)) {
+    return [];
+  }
+
+  return [
+    createVerificationIssue({
+      ruleId: "boolean-prefix",
+      category: "source-rule",
+      relativePath,
+      message: `boolean identifier must start with is/has/can/should: ${name}`,
+    }),
+  ];
+}
+
+export async function verifySourceRules(targetPath, contract, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const sectionOrder = Array.isArray(contract.profile.comment_section_blocks) ? contract.profile.comment_section_blocks : [];
+  const files = options.analysisContext?.sourceFiles ?? (await loadProjectSourceFiles(targetPath, options));
+  const errors = [];
+
+  for (const file of files) {
+    const { relativePath, ast, raw } = file;
+    const isSourceFile = relativePath.startsWith("src/");
+    const isTransportSourceFile = relativePath.startsWith("src/http/");
+    const exportedClasses = ast.statements.filter((statement) => isExportedClass(statement));
+
+    if (
+      isSourceFile &&
+      activeRuleIds.has("one-public-class-per-file") &&
+      shouldRunRule(options.onlyRuleIds, "one-public-class-per-file") &&
+      exportedClasses.length > 1
+    ) {
+      errors.push(
+        createVerificationIssue({
+          ruleId: "one-public-class-per-file",
+          category: "source-rule",
+          relativePath,
+          message: "source files may expose at most one public class",
+        }),
+      );
+    }
+
+    if (isSourceFile && activeRuleIds.has("class-section-order") && shouldRunRule(options.onlyRuleIds, "class-section-order") && exportedClasses.length > 0) {
+      errors.push(...verifySectionOrder(relativePath, raw, sectionOrder, exportedClasses[0]));
+    }
+
+    if (isSourceFile && activeRuleIds.has("feature-filename-role") && shouldRunRule(options.onlyRuleIds, "feature-filename-role")) {
+      errors.push(...verifyFeatureFilename(relativePath));
+    }
+
+    if (isSourceFile && activeRuleIds.has("feature-class-only") && shouldRunRule(options.onlyRuleIds, "feature-class-only")) {
+      errors.push(...verifyFeatureClassOnly(relativePath, ast));
+    }
+
+    if (isSourceFile && activeRuleIds.has("no-module-functions-in-class-files") && shouldRunRule(options.onlyRuleIds, "no-module-functions-in-class-files")) {
+      errors.push(...verifyNoModuleFunctionsInClassFiles(relativePath, ast));
+    }
+
+    visitNodes(ast, (node) => {
+      if (isSourceFile && !isTransportSourceFile && activeRuleIds.has("single-return") && shouldRunRule(options.onlyRuleIds, "single-return")) {
+        if (
+          ts.isFunctionDeclaration(node) ||
+          ts.isFunctionExpression(node) ||
+          ts.isArrowFunction(node) ||
+          ts.isMethodDeclaration(node) ||
+          ts.isConstructorDeclaration(node)
+        ) {
+          if (node.body && countReturnsInBody(node.body) > 1) {
+            errors.push(
+              createVerificationIssue({
+                ruleId: "single-return",
+                category: "source-rule",
+                relativePath,
+                message: "functions and methods outside src/http/ must use a single return statement",
+              }),
+            );
+          }
+        }
+      }
+
+      if (
+        isSourceFile &&
+        activeRuleIds.has("async-await-only") &&
+        shouldRunRule(options.onlyRuleIds, "async-await-only") &&
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression)
+      ) {
+        const callName = node.expression.name.text;
+
+        if (callName === "then" || callName === "catch") {
+          errors.push(
+            createVerificationIssue({
+              ruleId: "async-await-only",
+              category: "source-rule",
+              relativePath,
+              message: "promise chains are forbidden in src/; use async/await instead",
+            }),
+          );
+        }
+      }
+
+      if (
+        isSourceFile &&
+        activeRuleIds.has("canonical-config-import") &&
+        shouldRunRule(options.onlyRuleIds, "canonical-config-import") &&
+        ts.isImportDeclaration(node) &&
+        ts.isStringLiteral(node.moduleSpecifier)
+      ) {
+        errors.push(...verifyConfigImport(relativePath, node));
+      }
+
+      if (activeRuleIds.has("domain-specific-identifiers") && shouldRunRule(options.onlyRuleIds, "domain-specific-identifiers")) {
+        if (ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isPropertyDeclaration(node) || ts.isBindingElement(node)) {
+          errors.push(...verifyIdentifier("domain-specific-identifiers", relativePath, getIdentifierText(node.name)));
+        }
+      }
+
+      if (activeRuleIds.has("boolean-prefix") && shouldRunRule(options.onlyRuleIds, "boolean-prefix")) {
+        if ((ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isPropertyDeclaration(node)) && isBooleanLikeDeclaration(node)) {
+          errors.push(...verifyBooleanName(relativePath, getIdentifierText(node.name)));
+        }
+      }
+    });
+  }
+
+  return errors;
+}

package/lib/verify/testing-verifier.mjs

@@ -0,0 +1,113 @@
+import ts from "typescript";
+
+import { createContractIssue, createVerificationIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+import { getLineAndColumn } from "./source-analysis.mjs";
+
+const TEST_NON_DETERMINISM_PATTERNS = [
+  { pattern: /\bDate\.now\(/, label: "Date.now()" },
+  { pattern: /\bMath\.random\(/, label: "Math.random()" },
+  { pattern: /\bsetTimeout\(/, label: "setTimeout()" },
+  { pattern: /\bsetInterval\(/, label: "setInterval()" },
+  { pattern: /\bprocess\.env\.[A-Z0-9_]+\s*=/, label: "process.env mutation" },
+];
+
+function createIssue(contract, ruleId, relativePath, node, message, options = {}) {
+  const location = node && "getStart" in node && "getSourceFile" in node ? getLineAndColumn(node.getSourceFile(), node.getStart(node.getSourceFile())) : {};
+  return createContractIssue(contract, {
+    ruleId,
+    category: "testing",
+    relativePath,
+    line: location.line,
+    column: location.column,
+    message,
+    verificationMode: options.verificationMode,
+    confidence: options.confidence,
+    evidence: options.evidence,
+  });
+}
+
+function hasImportFrom(file, moduleName) {
+  return file.ast.statements.some(
+    (statement) => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === moduleName,
+  );
+}
+
+export async function verifyTestingRules(_targetPath, contract, analysisContext, changedFilesContext, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const issues = [];
+  const testFiles = analysisContext.sourceFiles.filter((file) => file.relativePath.startsWith("test/"));
+
+  for (const file of testFiles) {
+    if (activeRuleIds.has("node-test-runner-only") && shouldRunRule(options.onlyRuleIds, "node-test-runner-only") && !hasImportFrom(file, "node:test")) {
+      issues.push(createIssue(contract, "node-test-runner-only", file.relativePath, file.ast, "tests must import node:test"));
+    }
+
+    if (
+      activeRuleIds.has("assert-strict-preferred") &&
+      shouldRunRule(options.onlyRuleIds, "assert-strict-preferred") &&
+      !hasImportFrom(file, "node:assert/strict")
+    ) {
+      issues.push(createIssue(contract, "assert-strict-preferred", file.relativePath, file.ast, "tests must import node:assert/strict"));
+    }
+
+    if (activeRuleIds.has("no-ts-ignore-bypass") && shouldRunRule(options.onlyRuleIds, "no-ts-ignore-bypass")) {
+      const bypassMatch = file.raw.match(/@ts-ignore|@ts-expect-error|biome-ignore/);
+      if (bypassMatch) {
+        issues.push(createIssue(contract, "no-ts-ignore-bypass", file.relativePath, file.ast, `ignore directive is forbidden: ${bypassMatch[0]}`));
+      }
+    }
+
+    if (activeRuleIds.has("test-determinism-guards") && shouldRunRule(options.onlyRuleIds, "test-determinism-guards")) {
+      for (const signal of TEST_NON_DETERMINISM_PATTERNS) {
+        if (signal.pattern.test(file.raw)) {
+          issues.push(
+            createIssue(contract, "test-determinism-guards", file.relativePath, file.ast, "tests should avoid uncontrolled non-deterministic primitives", {
+              verificationMode: "heuristic",
+              confidence: "medium",
+              evidence: signal.label,
+            }),
+          );
+        }
+      }
+    }
+  }
+
+  if (activeRuleIds.has("test-file-naming") && shouldRunRule(options.onlyRuleIds, "test-file-naming")) {
+    for (const file of analysisContext.sourceFiles.filter((candidate) => candidate.relativePath.startsWith("test/"))) {
+      if (!file.relativePath.endsWith(".test.ts")) {
+        issues.push(createIssue(contract, "test-file-naming", file.relativePath, file.ast, "test files must use the .test.ts suffix"));
+      }
+    }
+  }
+
+  if (activeRuleIds.has("behavior-change-tests") && shouldRunRule(options.onlyRuleIds, "behavior-change-tests")) {
+    issues.push(...verifyBehaviorChangeTests(contract, changedFilesContext));
+  }
+
+  return issues;
+}
+
+function verifyBehaviorChangeTests(_contract, changedFilesContext) {
+  if (!changedFilesContext.available) {
+    return [];
+  }
+
+  const changedSourceFiles = changedFilesContext.files.filter((file) => file.startsWith("src/") && file.endsWith(".ts"));
+  const changedTestFiles = changedFilesContext.files.filter((file) => file.startsWith("test/") && file.endsWith(".ts"));
+
+  if (changedSourceFiles.length > 0 && changedTestFiles.length === 0) {
+    return [
+      createVerificationIssue({
+        ruleId: "behavior-change-tests",
+        category: "testing",
+        severity: "audit",
+        message: "source changes require at least one changed test file",
+        verificationMode: "audit",
+        confidence: "medium",
+        evidence: `${changedSourceFiles.length} src file(s) changed, 0 test file(s) changed`,
+      }),
+    ];
+  }
+
+  return [];
+}

package/lib/verify/tooling-verifier.mjs

@@ -0,0 +1,82 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { createContractIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+
+const REQUIRED_SCRIPT_NAMES = ["standards:check", "check", "fix", "lint", "format:check", "typecheck", "test"];
+
+function createIssue(contract, ruleId, relativePath, message, options = {}) {
+  return createContractIssue(contract, {
+    ruleId,
+    category: "tooling",
+    relativePath,
+    message,
+    verificationMode: options.verificationMode,
+    confidence: options.confidence,
+    evidence: options.evidence,
+  });
+}
+
+export async function verifyTooling(targetPath, contract, packageJson, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const issues = [];
+  const scripts = packageJson.scripts ?? {};
+  const template = contract.project.template;
+
+  if (activeRuleIds.has("required-scripts") && shouldRunRule(options.onlyRuleIds, "required-scripts")) {
+    for (const scriptName of REQUIRED_SCRIPT_NAMES) {
+      if (typeof scripts[scriptName] !== "string" || scripts[scriptName].trim().length === 0) {
+        issues.push(createIssue(contract, "required-scripts", "package.json", `missing required script: ${scriptName}`));
+      }
+    }
+  }
+
+  if (activeRuleIds.has("standards-check-script") && shouldRunRule(options.onlyRuleIds, "standards-check-script")) {
+    if (typeof scripts["standards:check"] !== "string" || !scripts["standards:check"].includes("code-standards verify")) {
+      issues.push(createIssue(contract, "standards-check-script", "package.json", "standards:check must execute code-standards verify"));
+    }
+  }
+
+  if (activeRuleIds.has("package-exports-alignment") && shouldRunRule(options.onlyRuleIds, "package-exports-alignment")) {
+    const tsconfigJson = await readOptionalJson(path.join(targetPath, "tsconfig.json"));
+    const expectedTsconfig = template === "node-service" ? "@sha3/code/tsconfig/node-service.json" : "@sha3/code/tsconfig/node-lib.json";
+
+    if (tsconfigJson.extends !== expectedTsconfig) {
+      issues.push(createIssue(contract, "package-exports-alignment", "tsconfig.json", `tsconfig.json must extend ${expectedTsconfig}`));
+    }
+
+    const biomeJson = await readOptionalJson(path.join(targetPath, "biome.json"));
+    if (!isExpectedBiomeConfig(biomeJson)) {
+      issues.push(createIssue(contract, "package-exports-alignment", "biome.json", "biome.json must stay aligned with the exported @sha3/code biome baseline"));
+    }
+  }
+
+  return issues;
+}
+
+async function readOptionalJson(absolutePath) {
+  const raw = await readFile(absolutePath, "utf8").catch(() => null);
+  if (!raw) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function isExpectedBiomeConfig(biomeJson) {
+  return (
+    biomeJson?.formatter?.lineWidth === 160 &&
+    biomeJson?.javascript?.formatter?.quoteStyle === "double" &&
+    biomeJson?.linter?.rules?.correctness?.noUnusedVariables === "error" &&
+    biomeJson?.linter?.rules?.correctness?.noUnusedFunctionParameters === "error" &&
+    biomeJson?.linter?.rules?.correctness?.noUnusedPrivateClassMembers === "error" &&
+    biomeJson?.linter?.rules?.correctness?.noUnusedImports === "error" &&
+    Array.isArray(biomeJson?.files?.ignore) &&
+    biomeJson.files.ignore.includes(".code-standards") &&
+    biomeJson.files.ignore.includes("dist")
+  );
+}