@sha3/code 1.0.0

package/lib/cli/run-profile.mjs

@@ -0,0 +1,46 @@
+import path from "node:path";
+
+import { DEFAULT_PROFILE } from "../constants.mjs";
+import { getBundledProfilePath, loadProfileSchema, resolvePackageRoot } from "../paths.mjs";
+import { createProfileInteractively, validateProfile } from "../profile.mjs";
+import { normalizeProfile, pathExists, writeJsonFile } from "../utils/fs.mjs";
+import { promptYesNo, withReadline } from "../utils/prompts.mjs";
+
+export async function runProfile(rawOptions) {
+  if (rawOptions.help) {
+    const { printUsage } = await import("./parse-args.mjs");
+    printUsage();
+    return;
+  }
+
+  const packageRoot = resolvePackageRoot();
+  const schema = await loadProfileSchema(packageRoot);
+  const defaultProfilePath = getBundledProfilePath(packageRoot);
+  const outputPath = rawOptions.profilePath ? path.resolve(process.cwd(), rawOptions.profilePath) : defaultProfilePath;
+  const shouldUseNonInteractive = rawOptions.nonInteractive || !process.stdin.isTTY;
+  const exists = await pathExists(outputPath);
+
+  if (exists && !rawOptions.forceProfile) {
+    if (shouldUseNonInteractive) {
+      throw new Error(`Profile already exists at ${outputPath}. Use --force-profile to overwrite.`);
+    }
+
+    const shouldOverwrite = await withReadline((rl) => promptYesNo(rl, `Profile already exists at ${outputPath}. Overwrite?`, false));
+    if (!shouldOverwrite) {
+      console.log("Profile update cancelled.");
+      return;
+    }
+  }
+
+  let profile = normalizeProfile(DEFAULT_PROFILE);
+
+  if (shouldUseNonInteractive) {
+    validateProfile(profile, schema, "built-in defaults");
+  } else {
+    profile = await createProfileInteractively(profile);
+    validateProfile(profile, schema, "interactive answers");
+  }
+
+  await writeJsonFile(outputPath, profile);
+  console.log(`Profile written to ${outputPath}`);
+}

package/lib/cli/run-refactor.mjs

@@ -0,0 +1,152 @@
+import path from "node:path";
+
+import { TEMPLATE_NAMES } from "../constants.mjs";
+import { loadProfileSchema, readPackageVersion, resolvePackageRoot } from "../paths.mjs";
+import { resolveProfileForRefactor } from "../profile.mjs";
+import { generateAiInstructions } from "../project/ai-instructions.mjs";
+import { ensureBiomeIgnore } from "../project/biome-ignore.mjs";
+import { applyManagedFiles } from "../project/managed-files.mjs";
+import {
+  applyPackageCoordinates,
+  extractRepositoryUrl,
+  readProjectPackageJson,
+  refreshPackageDependencyVersions,
+  updateCodeStandardsMetadata,
+  writeProjectPackageJson,
+} from "../project/package-metadata.mjs";
+import { resolveTemplateForRefactor, validateInitResources } from "../project/template-resolution.mjs";
+import { materializeRefactorContext, removeManagedProjectSurface } from "../refactor/materialize-refactor-context.mjs";
+import { resolvePreservationDecisions } from "../refactor/preservation-questions.mjs";
+import { extractPublicContract } from "../refactor/public-contract-extractor.mjs";
+import { renderAnalysisSummary } from "../refactor/render-analysis-summary.mjs";
+import { analyzeProjectSource } from "../refactor/source-analysis.mjs";
+import { formatFilesWithBiome, pathExists, readJsonFile, runCommand } from "../utils/fs.mjs";
+import { askChoice, withReadline } from "../utils/prompts.mjs";
+import { defaultPackageNameForProject, normalizePackageName, normalizeRepositoryUrl } from "../utils/text.mjs";
+import { printRefactorGuidance } from "./post-run-guidance.mjs";
+
+async function resolveTemplate(rawOptions, projectPackageJson, targetPath) {
+  try {
+    return await resolveTemplateForRefactor(rawOptions, projectPackageJson, targetPath);
+  } catch (_error) {
+    if (rawOptions.yes || !process.stdin.isTTY) {
+      return "node-lib";
+    }
+
+    return withReadline((rl) => askChoice(rl, "Choose template for refactor", TEMPLATE_NAMES, "node-lib"));
+  }
+}
+
+async function readInstalledCodeStandardsVersion(targetPath) {
+  const nodeModulesPath = path.join(targetPath, "node_modules");
+  const installedPackagePath = path.join(nodeModulesPath, "@sha3", "code", "package.json");
+
+  if (!(await pathExists(installedPackagePath))) {
+    return null;
+  }
+
+  const installedPackageJson = await readJsonFile(installedPackagePath);
+  return typeof installedPackageJson.version === "string" && installedPackageJson.version.length > 0 ? installedPackageJson.version : null;
+}
+
+async function ensureDependenciesInstalled(targetPath, installRequested, packageVersion) {
+  const nodeModulesPath = path.join(targetPath, "node_modules");
+
+  if (installRequested) {
+    console.log("Installing dependencies...");
+    await runCommand("npm", ["install"], targetPath);
+    return;
+  }
+
+  if (await pathExists(nodeModulesPath)) {
+    const installedCodeStandardsVersion = await readInstalledCodeStandardsVersion(targetPath);
+
+    if (installedCodeStandardsVersion === packageVersion) {
+      return;
+    }
+
+    console.log(
+      installedCodeStandardsVersion
+        ? `Installing dependencies because installed @sha3/code is ${installedCodeStandardsVersion} and expected ${packageVersion}...`
+        : "Installing dependencies because installed @sha3/code was not found in node_modules...",
+    );
+    await runCommand("npm", ["install"], targetPath);
+    return;
+  }
+
+  console.log("Installing dependencies because node_modules is missing...");
+  await runCommand("npm", ["install"], targetPath);
+}
+
+export async function runRefactor(rawOptions) {
+  if (rawOptions.help) {
+    const { printUsage } = await import("./parse-args.mjs");
+    printUsage();
+    return;
+  }
+
+  const targetPath = path.resolve(process.cwd());
+  const packageRoot = resolvePackageRoot();
+  const packageVersion = await readPackageVersion(packageRoot);
+  const schema = await loadProfileSchema(packageRoot);
+  const { packageJsonPath, packageJson: projectPackageJson } = await readProjectPackageJson(targetPath);
+  const projectMetadata = projectPackageJson.codeStandards ?? {};
+  const template = await resolveTemplate(rawOptions, projectPackageJson, targetPath);
+  const { templateDir } = await validateInitResources(packageRoot, template);
+  const profileResolution = await resolveProfileForRefactor(packageRoot, targetPath, rawOptions, schema, projectMetadata);
+  const inferredProjectName = path.basename(targetPath);
+  const projectName = inferredProjectName && inferredProjectName !== path.sep ? inferredProjectName : "my-project";
+  const existingPackageName =
+    typeof projectPackageJson.name === "string" && projectPackageJson.name.length > 0 ? projectPackageJson.name : defaultPackageNameForProject(projectName);
+  const packageName = rawOptions.packageName ? normalizePackageName(rawOptions.packageName, projectName) : existingPackageName;
+  const repositoryUrl = normalizeRepositoryUrl(rawOptions.repositoryUrl ?? extractRepositoryUrl(projectPackageJson), packageName);
+  const tokens = { projectName, packageName, packageVersion, year: String(new Date().getFullYear()) };
+
+  console.log("Analyzing current project...");
+  const sourceAnalysis = await analyzeProjectSource(targetPath, projectPackageJson);
+  const preservation = await resolvePreservationDecisions(rawOptions);
+  const publicContract = extractPublicContract(projectPackageJson, template, profileResolution.profilePathForMetadata, sourceAnalysis);
+  const analysisSummary = renderAnalysisSummary(projectPackageJson, sourceAnalysis, preservation);
+
+  console.log("Creating refactor snapshot...");
+  await materializeRefactorContext(targetPath, publicContract, preservation, analysisSummary);
+
+  console.log("Rebuilding managed project surface...");
+  await removeManagedProjectSurface(templateDir, targetPath);
+  const managedResults = await applyManagedFiles({
+    templateDir,
+    targetDir: targetPath,
+    tokens,
+    projectPackageJson,
+    dryRun: false,
+  });
+
+  const contract = await generateAiInstructions({
+    packageRoot,
+    packageVersion,
+    targetDir: targetPath,
+    tokens,
+    profile: profileResolution.profile,
+    template,
+    withAiAdapters: rawOptions.withAiAdapters,
+    workflow: "refactor",
+  });
+  await ensureBiomeIgnore(targetPath, contract.managedFiles);
+
+  const packageWithCoordinates = applyPackageCoordinates(managedResults.mergedPackageJson, packageName, repositoryUrl);
+  const packageWithRefreshedDependencies = await refreshPackageDependencyVersions(packageWithCoordinates, {
+    cwd: targetPath,
+    codeStandardsVersion: packageVersion,
+  });
+  const packageWithMetadata = updateCodeStandardsMetadata(packageWithRefreshedDependencies, {
+    template,
+    profilePath: profileResolution.profilePathForMetadata,
+    withAiAdapters: rawOptions.withAiAdapters,
+    lastRefactorWith: packageVersion,
+  });
+  await writeProjectPackageJson(packageJsonPath, packageWithMetadata);
+  await formatFilesWithBiome(packageRoot, targetPath, ["package.json", "ai/contract.json"]);
+
+  await ensureDependenciesInstalled(targetPath, rawOptions.install, packageVersion);
+  await printRefactorGuidance(targetPath);
+}

package/lib/cli/run-verify.mjs

@@ -0,0 +1,67 @@
+import { loadRuleCatalog } from "../contract/load-rule-catalog.mjs";
+import { resolvePackageRoot } from "../paths.mjs";
+import { explainRule } from "../verify/explain-rule.mjs";
+import { PROJECT_VERIFY_RULE_IDS } from "../verify/issue-helpers.mjs";
+import { verifyProject } from "../verify/project-verifier.mjs";
+import { renderJsonReport } from "../verify/render-json-report.mjs";
+import { renderTextReport } from "../verify/render-text-report.mjs";
+
+export async function runVerify(rawOptions) {
+  if (rawOptions.help) {
+    const { printUsage } = await import("./parse-args.mjs");
+    printUsage();
+    return;
+  }
+
+  const packageRoot = resolvePackageRoot();
+  const ruleCatalog = await loadRuleCatalog(packageRoot);
+
+  if (rawOptions.explainRuleId) {
+    const rule = ruleCatalog.rules.find((candidate) => candidate.id === rawOptions.explainRuleId);
+
+    if (!rule) {
+      throw new Error(`Unknown rule id for --explain: ${rawOptions.explainRuleId}`);
+    }
+
+    console.log(explainRule(rule));
+    return;
+  }
+
+  if (rawOptions.onlyRuleIds) {
+    const knownRuleIds = new Set([...PROJECT_VERIFY_RULE_IDS, ...ruleCatalog.rules.map((rule) => rule.id)]);
+
+    for (const ruleId of rawOptions.onlyRuleIds) {
+      if (!knownRuleIds.has(ruleId)) {
+        throw new Error(`Unknown rule id for --only: ${ruleId}`);
+      }
+    }
+  }
+
+  const targetPath = process.cwd();
+  const result = await verifyProject(targetPath, {
+    onlyRuleIds: rawOptions.onlyRuleIds,
+    files: rawOptions.files,
+    strict: rawOptions.strict,
+    changedAgainst: rawOptions.changedAgainst,
+    staged: rawOptions.staged,
+    allFiles: rawOptions.allFiles,
+  });
+
+  if (rawOptions.report === "json") {
+    console.log(renderJsonReport(result));
+    if (!result.ok) {
+      throw new Error(`Verification failed with ${result.summary.errorCount} error(s) and ${result.summary.warningCount} warning(s).`);
+    }
+    return;
+  }
+
+  const output = renderTextReport(result);
+
+  if (result.ok) {
+    console.log(output);
+    return;
+  }
+
+  console.error(output);
+  throw new Error(`Verification failed with ${result.summary.errorCount} error(s) and ${result.summary.warningCount} warning(s).`);
+}

package/lib/constants.mjs

@@ -0,0 +1,167 @@
+export const TEMPLATE_NAMES = ["node-lib", "node-service"];
+export const CODE_STANDARDS_METADATA_KEY = "codeStandards";
+export const CONTRACT_FORMAT_VERSION = "v2";
+export const NODE_LIB_TEMPLATE_SIGNATURE = { main: "dist/index.js", types: "dist/index.d.ts" };
+export const NODE_SERVICE_START_SIGNATURE = "node --import tsx src/main.ts";
+export const REFACTOR_ARTIFACT_ROOT = ".code-standards/refactor-source";
+export const REFACTOR_LATEST_DIR = `${REFACTOR_ARTIFACT_ROOT}/latest`;
+export const REFACTOR_PUBLIC_CONTRACT_PATH = `${REFACTOR_ARTIFACT_ROOT}/public-contract.json`;
+export const REFACTOR_PRESERVATION_PATH = `${REFACTOR_ARTIFACT_ROOT}/preservation.json`;
+export const REFACTOR_ANALYSIS_SUMMARY_PATH = `${REFACTOR_ARTIFACT_ROOT}/analysis-summary.md`;
+export const MANAGED_PROJECT_SURFACE_ROOTS = [
+  "AGENTS.md",
+  "ai",
+  "prompts",
+  ".vscode",
+  ".biomeignore",
+  "biome.json",
+  "README.md",
+  "src",
+  "test",
+  "scripts",
+  "tsconfig.json",
+  "tsconfig.build.json",
+  "ecosystem.config.cjs",
+  ".gitignore",
+  "eslint.config.mjs",
+  "prettier.config.cjs",
+];
+export const TEMPLATE_REQUIRED_FILES = {
+  "node-lib": ["src/config.ts", "src/package-info/package-info.service.ts", "src/index.ts", "test/package-info.test.ts"],
+  "node-service": [
+    "src/config.ts",
+    "src/app-info/app-info.service.ts",
+    "src/http/http-server.service.ts",
+    "src/app/service-runtime.service.ts",
+    "src/index.ts",
+    "src/main.ts",
+    "test/service-runtime.test.ts",
+  ],
+};
+
+export const PROFILE_KEY_ORDER = [
+  "version",
+  "paradigm",
+  "function_size_policy",
+  "return_policy",
+  "class_design",
+  "comments_policy",
+  "testing_policy",
+  "architecture",
+  "error_handling",
+  "async_style",
+  "class_file_policy",
+  "type_contract_policy",
+  "mutability",
+  "comment_section_blocks",
+  "comment_section_format",
+  "comment_sections_required_when_empty",
+  "if_requires_braces",
+  "readme_style",
+  "rule_severity_model",
+  "language",
+  "examples_density",
+  "instruction_file_location",
+];
+
+export const DEFAULT_PROFILE = {
+  version: "v2",
+  paradigm: "class-first",
+  function_size_policy: "max_30_lines_soft",
+  return_policy: "single_return_strict_no_exceptions",
+  class_design: "constructor_injection",
+  comments_policy: "extensive",
+  testing_policy: "tests_required_for_behavior_change",
+  architecture: "feature_folders",
+  error_handling: "mixed",
+  async_style: "async_await_only",
+  class_file_policy: "one_public_class_per_file",
+  type_contract_policy: "prefer_types_over_interfaces",
+  mutability: "immutability_preferred",
+  comment_section_blocks: [
+    "imports:externals",
+    "imports:internals",
+    "consts",
+    "types",
+    "class",
+    "private:attributes",
+    "protected:attributes",
+    "public:properties",
+    "constructor",
+    "static:properties",
+    "factory",
+    "private:methods",
+    "protected:methods",
+    "public:methods",
+    "static:methods",
+  ],
+  comment_section_format: "jsdoc-section-tag",
+  comment_sections_required_when_empty: false,
+  if_requires_braces: true,
+  readme_style: "top-tier",
+  rule_severity_model: "tiered",
+  language: "english_technical",
+  examples_density: "rule_with_good_bad_examples",
+  instruction_file_location: "root_agents_md",
+};
+
+export const PROFILE_QUESTIONS = [
+  { key: "paradigm", prompt: "Preferred paradigm", options: ["class-first", "hybrid", "functional-first"] },
+  { key: "function_size_policy", prompt: "Function size policy", options: ["max_20_lines_hard", "max_30_lines_soft", "no_fixed_limit"] },
+  { key: "return_policy", prompt: "Return policy", options: ["single_return_strict_no_exceptions", "single_return_with_guard_clauses", "free_return_style"] },
+  { key: "class_design", prompt: "Class design policy", options: ["constructor_injection", "internal_instantiation", "mixed"] },
+  { key: "comments_policy", prompt: "Comments policy", options: ["extensive", "complex_logic_only", "minimal"] },
+  { key: "testing_policy", prompt: "Testing policy", options: ["tests_required_for_behavior_change", "tests_critical_only", "tests_optional"] },
+  { key: "architecture", prompt: "Architecture style", options: ["feature_folders", "layered", "simple_src_lib"] },
+  { key: "error_handling", prompt: "Error handling style", options: ["mixed", "exceptions_with_typed_errors", "result_either"] },
+  { key: "async_style", prompt: "Async style", options: ["async_await_only", "promise_chains", "both"] },
+  { key: "class_file_policy", prompt: "Class/file policy", options: ["one_public_class_per_file", "multiple_classes_allowed", "no_rule"] },
+  { key: "type_contract_policy", prompt: "Type contract policy", options: ["prefer_types_over_interfaces", "interfaces_everywhere", "interfaces_public_only"] },
+  { key: "mutability", prompt: "Mutability policy", options: ["immutability_preferred", "immutability_strict", "mutable_pragmatic"] },
+  { key: "rule_severity_model", prompt: "Rule severity model", options: ["tiered", "all_preferred"] },
+  { key: "language", prompt: "Instruction language", options: ["english_technical", "spanish_technical", "bilingual"] },
+  { key: "examples_density", prompt: "Examples density", options: ["rule_with_good_bad_examples", "rules_only", "rules_plus_long_templates"] },
+  { key: "instruction_file_location", prompt: "Instruction file location", options: ["root_agents_md", "ai_instructions_md", "both"] },
+];
+
+export const README_REQUIRED_HEADINGS_BY_TEMPLATE = {
+  "node-lib": [
+    "## TL;DR",
+    "## Why",
+    "## Main Capabilities",
+    "## Installation",
+    "## Usage",
+    "## Examples",
+    "## Public API",
+    "## Configuration",
+    "## Compatibility",
+    "## Scripts",
+    "## Structure",
+    "## Troubleshooting",
+    "## AI Workflow",
+  ],
+  "node-service": [
+    "## TL;DR",
+    "## Why",
+    "## Main Capabilities",
+    "## Installation",
+    "## Running Locally",
+    "## Usage",
+    "## Examples",
+    "## Public API",
+    "## Configuration",
+    "## Compatibility",
+    "## Scripts",
+    "## Structure",
+    "## Troubleshooting",
+    "## AI Workflow",
+  ],
+};
+
+export const MANAGED_AI_FILES = ["AGENTS.md", "SKILLS.md", "ai/contract.json", "ai/rules.md"];
+export const AI_ADAPTER_FILES = ["codex.md", "cursor.md", "copilot.md", "windsurf.md"];
+
+export function isRefactorArtifactPath(relativePath) {
+  const normalizedPath = relativePath.split("\\").join("/");
+  return normalizedPath === REFACTOR_ARTIFACT_ROOT || normalizedPath.startsWith(`${REFACTOR_ARTIFACT_ROOT}/`);
+}

package/lib/contract/load-rule-catalog.mjs

@@ -0,0 +1,12 @@
+import { getContractSchemaPath, getRuleCatalogPath, getRuleCatalogSchemaPath, loadJsonFileAt } from "../paths.mjs";
+import { validateAgainstSchema } from "../utils/fs.mjs";
+
+export async function loadRuleCatalog(packageRoot) {
+  const [catalog, schema] = await Promise.all([loadJsonFileAt(getRuleCatalogPath(packageRoot)), loadJsonFileAt(getRuleCatalogSchemaPath(packageRoot))]);
+  validateAgainstSchema(catalog, schema, "resources/ai/rule-catalog.json");
+  return catalog;
+}
+
+export async function loadContractSchema(packageRoot) {
+  return loadJsonFileAt(getContractSchemaPath(packageRoot));
+}

package/lib/contract/render-agents.mjs

@@ -0,0 +1,79 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { replaceTokens } from "../utils/text.mjs";
+
+function buildRuleLines(rules, verificationMode) {
+  return rules
+    .filter((rule) => rule.verificationMode === verificationMode)
+    .map((rule) => `- \`${rule.id}\`: ${rule.summary} (severity: ${rule.severity}, enforced by: ${rule.enforcedBy.join(", ")}, confidence: ${rule.confidence})`)
+    .join("\n");
+}
+
+function buildManagedFiles(managedFiles) {
+  return managedFiles.map((filePath) => `- \`${filePath}\``).join("\n");
+}
+
+export async function renderProjectAgents(packageRoot, targetDir, contract) {
+  const templatePath = path.join(packageRoot, "resources", "ai", "templates", "agents.project.template.md");
+  const template = await readFile(templatePath, "utf8");
+  const rendered = replaceTokens(template, {
+    projectName: contract.project.name,
+    contractVersion: contract.formatVersion,
+    generatedByVersion: contract.generatedByVersion,
+    profileSummary: Object.entries(contract.profile)
+      .map(([key, value]) => `- \`${key}\`: \`${Array.isArray(value) ? value.join(" | ") : String(value)}\``)
+      .join("\n"),
+    deterministicRules: buildRuleLines(contract.rules, "deterministic"),
+    heuristicRules: buildRuleLines(contract.rules, "heuristic"),
+    auditRules: buildRuleLines(contract.rules, "audit"),
+    managedFiles: buildManagedFiles(contract.managedFiles),
+  });
+
+  await writeFile(path.join(targetDir, "AGENTS.md"), rendered, "utf8");
+}
+
+export async function renderProjectRules(packageRoot, targetDir, contract) {
+  const templatePath = path.join(packageRoot, "resources", "ai", "templates", "rules.project.template.md");
+  const template = await readFile(templatePath, "utf8");
+  const rendered = replaceTokens(template, {
+    deterministicRules: buildRuleLines(contract.rules, "deterministic"),
+    heuristicRules: buildRuleLines(contract.rules, "heuristic"),
+    auditRules: buildRuleLines(contract.rules, "audit"),
+  });
+
+  await writeFile(path.join(targetDir, "ai", "rules.md"), rendered, "utf8");
+}
+
+export async function renderSkillFiles(packageRoot, targetDir, tokens) {
+  const { copyTemplateDirectory } = await import("../utils/fs.mjs");
+  const skillsTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "skills");
+  await copyTemplateDirectory(skillsTemplateDir, path.join(targetDir, "skills"), tokens);
+
+  const skillsIndexTemplatePath = path.join(packageRoot, "resources", "ai", "templates", "skills.index.template.md");
+  const skillsIndexTemplate = await readFile(skillsIndexTemplatePath, "utf8");
+  await writeFile(path.join(targetDir, "SKILLS.md"), replaceTokens(skillsIndexTemplate, tokens), "utf8");
+}
+
+export async function renderAdapterFiles(packageRoot, targetDir, tokens) {
+  const adaptersTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "adapters");
+  const adaptersTarget = path.join(targetDir, "ai");
+  const { mkdir, readdir } = await import("node:fs/promises");
+
+  await mkdir(adaptersTarget, { recursive: true });
+  const entries = await readdir(adaptersTemplateDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".template.md")) {
+      continue;
+    }
+
+    const raw = await readFile(path.join(adaptersTemplateDir, entry.name), "utf8");
+    await writeFile(path.join(adaptersTarget, entry.name.replace(/\.template\.md$/, ".md")), replaceTokens(raw, tokens), "utf8");
+  }
+}
+
+export async function renderExampleFiles(packageRoot, targetDir, tokens) {
+  const { copyTemplateDirectory } = await import("../utils/fs.mjs");
+  await copyTemplateDirectory(path.join(packageRoot, "resources", "ai", "templates", "examples"), path.join(targetDir, "ai", "examples"), tokens);
+}

package/lib/contract/render-contract-json.mjs

@@ -0,0 +1,7 @@
+import path from "node:path";
+
+import { writeJsonFile } from "../utils/fs.mjs";
+
+export async function renderContractJson(targetDir, contract) {
+  await writeJsonFile(path.join(targetDir, "ai", "contract.json"), contract);
+}

package/lib/contract/resolve-contract.mjs

@@ -0,0 +1,52 @@
+import { CONTRACT_FORMAT_VERSION } from "../constants.mjs";
+
+function matchesProfileOverride(rule, profile) {
+  const overrides = rule.profileOverrides ?? [];
+
+  if (overrides.length === 0) {
+    return true;
+  }
+
+  return overrides.every((override) => {
+    if (override.equals !== undefined) {
+      return profile[override.key] === override.equals;
+    }
+
+    if (Array.isArray(override.oneOf)) {
+      return override.oneOf.includes(profile[override.key]);
+    }
+
+    return true;
+  });
+}
+
+export function resolveContract(options) {
+  const { packageVersion, projectName, template, profile, withAiAdapters, managedFiles, ruleCatalog } = options;
+  const activeRules = ruleCatalog.rules
+    .filter((rule) => matchesProfileOverride(rule, profile))
+    .map((rule) => ({
+      id: rule.id,
+      title: rule.title,
+      summary: rule.summary,
+      severity: rule.severity,
+      kind: rule.kind,
+      deterministic: rule.verificationMode === "deterministic",
+      verificationMode: rule.verificationMode,
+      verificationSource: rule.verificationSource,
+      implementedBy: rule.implementedBy,
+      requiresContext: rule.requiresContext,
+      confidence: rule.confidence,
+      appliesTo: rule.appliesTo,
+      enforcedBy: rule.enforcedBy,
+      examples: rule.examples,
+    }));
+
+  return {
+    formatVersion: CONTRACT_FORMAT_VERSION,
+    generatedByVersion: packageVersion,
+    project: { name: projectName, template, withAiAdapters },
+    profile,
+    managedFiles,
+    rules: activeRules,
+  };
+}

package/lib/paths.mjs

@@ -0,0 +1,50 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { readJsonFile } from "./utils/fs.mjs";
+
+export function resolvePackageRoot() {
+  const callerPath = fileURLToPath(import.meta.url);
+  return path.resolve(path.dirname(callerPath), "..");
+}
+
+export async function readPackageVersion(packageRoot) {
+  const packageJson = await readJsonFile(path.join(packageRoot, "package.json"));
+
+  if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error("Package version is missing in the CLI package.json.");
+  }
+
+  return packageJson.version;
+}
+
+export function getBundledProfilePath(packageRoot) {
+  return path.join(packageRoot, "profiles", "default.profile.json");
+}
+
+export function getProfileSchemaPath(packageRoot) {
+  return path.join(packageRoot, "profiles", "schema.json");
+}
+
+export function getRuleCatalogPath(packageRoot) {
+  return path.join(packageRoot, "resources", "ai", "rule-catalog.json");
+}
+
+export function getRuleCatalogSchemaPath(packageRoot) {
+  return path.join(packageRoot, "resources", "ai", "rule-catalog.schema.json");
+}
+
+export function getContractSchemaPath(packageRoot) {
+  return path.join(packageRoot, "resources", "ai", "contract.schema.json");
+}
+
+export async function loadJsonFileAt(filePath) {
+  await access(filePath, constants.R_OK);
+  return readJsonFile(filePath);
+}
+
+export async function loadProfileSchema(packageRoot) {
+  return loadJsonFileAt(getProfileSchemaPath(packageRoot));
+}