@sha3/code-standards 0.1.0

package/eslint/base.mjs

@@ -0,0 +1,36 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: ["**/node_modules/**", "**/dist/**", "**/coverage/**", "**/.git/**"]
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.{js,mjs,cjs,ts,mts,cts,tsx}"],
+    rules: {
+      curly: ["error", "all"]
+    }
+  },
+  {
+    files: ["**/*.{ts,mts,cts,tsx}"],
+    rules: {
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_"
+        }
+      ]
+    }
+  },
+  {
+    files: ["**/*.cjs"],
+    rules: {
+      "@typescript-eslint/no-require-imports": "off"
+    }
+  }
+);

package/eslint/node.mjs

@@ -0,0 +1,14 @@
+import globals from "globals";
+import baseConfig from "./base.mjs";
+
+export default [
+  ...baseConfig,
+  {
+    files: ["**/*.{js,mjs,cjs,ts,mts,cts,tsx}"],
+    languageOptions: {
+      globals: {
+        ...globals.node
+      }
+    }
+  }
+];

package/eslint/test.mjs

@@ -0,0 +1,19 @@
+import globals from "globals";
+import nodeConfig from "./node.mjs";
+
+export default [
+  ...nodeConfig,
+  {
+    files: [
+      "**/*.test.{js,mjs,cjs,ts,mts,cts}",
+      "**/*.spec.{js,mjs,cjs,ts,mts,cts}",
+      "test/**/*.{js,mjs,cjs,ts,mts,cts}"
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.mocha,
+        ...globals.node
+      }
+    }
+  }
+];

package/index.mjs

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+import eslintBase from "./eslint/base.mjs";
+import eslintNode from "./eslint/node.mjs";
+import eslintTest from "./eslint/test.mjs";
+
+const require = createRequire(import.meta.url);
+const prettierConfig = require("./prettier/index.cjs");
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+export { eslintBase, eslintNode, eslintTest, prettierConfig };
+
+export const tsconfigPaths = {
+  base: path.join(rootDir, "tsconfig", "base.json"),
+  nodeLib: path.join(rootDir, "tsconfig", "node-lib.json"),
+  nodeService: path.join(rootDir, "tsconfig", "node-service.json")
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@sha3/code-standards",
+  "version": "0.1.0",
+  "description": "AI-first code standards, tooling exports, and project initializer",
+  "type": "module",
+  "bin": {
+    "code-standards": "./bin/code-standards.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./eslint/base": "./eslint/base.mjs",
+    "./eslint/node": "./eslint/node.mjs",
+    "./eslint/test": "./eslint/test.mjs",
+    "./prettier": "./prettier/index.cjs",
+    "./tsconfig/base.json": "./tsconfig/base.json",
+    "./tsconfig/node-lib.json": "./tsconfig/node-lib.json",
+    "./tsconfig/node-service.json": "./tsconfig/node-service.json"
+  },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "ai",
+    "bin",
+    "eslint",
+    "index.mjs",
+    "prettier",
+    "resources",
+    "standards",
+    "templates",
+    "tsconfig",
+    "profiles"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "scripts": {
+    "check": "npm run standards:validate && npm run profile:validate && npm run lint && npm run format:check && npm run typecheck && npm run test",
+    "fix": "npm run lint:fix && npm run format:write",
+    "standards:validate": "node scripts/validate-standards.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format:check": "prettier --check .",
+    "format:write": "prettier --write .",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node scripts/smoke-fixtures.mjs && node --test ./test/*.test.mjs",
+    "release:check": "npm run check",
+    "release:publish": "node scripts/release-publish.mjs",
+    "hooks:install": "git config core.hooksPath .githooks",
+    "profile:validate": "node scripts/validate-profile.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@types/node": "^22.13.10",
+    "ajv": "^8.17.1",
+    "eslint": "^9.20.1",
+    "globals": "^15.15.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.24.1"
+  }
+}

package/prettier/index.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  printWidth: 100,
+  tabWidth: 2,
+  useTabs: false,
+  semi: true,
+  singleQuote: false,
+  trailingComma: "none",
+  bracketSpacing: true,
+  arrowParens: "always"
+};

package/profiles/default.profile.json

@@ -0,0 +1,38 @@
+{
+  "version": "v1",
+  "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": "exceptions_with_typed_errors",
+  "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",
+    "private:attributes",
+    "private:properties",
+    "public:properties",
+    "constructor",
+    "static:properties",
+    "factory",
+    "private:methods",
+    "public:methods",
+    "static:methods"
+  ],
+  "comment_section_format": "jsdoc-section-tag",
+  "comment_sections_required_when_empty": true,
+  "if_requires_braces": true,
+  "readme_style": "top-tier",
+  "rule_severity_model": "all_blocking",
+  "language": "english_technical",
+  "examples_density": "rule_with_good_bad_examples",
+  "instruction_file_location": "root_agents_md"
+}

package/profiles/schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sha3.dev/code-standards/profile.schema.json",
+  "title": "AI Style Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "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"
+  ],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "v1"
+    },
+    "paradigm": {
+      "type": "string",
+      "enum": ["class-first", "functional-first", "hybrid"]
+    },
+    "function_size_policy": {
+      "type": "string",
+      "enum": ["max_20_lines_hard", "max_30_lines_soft", "no_fixed_limit"]
+    },
+    "return_policy": {
+      "type": "string",
+      "enum": [
+        "single_return_strict_no_exceptions",
+        "single_return_with_guard_clauses",
+        "free_return_style"
+      ]
+    },
+    "class_design": {
+      "type": "string",
+      "enum": ["constructor_injection", "internal_instantiation", "mixed"]
+    },
+    "comments_policy": {
+      "type": "string",
+      "enum": ["extensive", "complex_logic_only", "minimal"]
+    },
+    "testing_policy": {
+      "type": "string",
+      "enum": ["tests_required_for_behavior_change", "tests_critical_only", "tests_optional"]
+    },
+    "architecture": {
+      "type": "string",
+      "enum": ["feature_folders", "layered", "simple_src_lib"]
+    },
+    "error_handling": {
+      "type": "string",
+      "enum": ["exceptions_with_typed_errors", "result_either", "mixed"]
+    },
+    "async_style": {
+      "type": "string",
+      "enum": ["async_await_only", "promise_chains", "both"]
+    },
+    "class_file_policy": {
+      "type": "string",
+      "enum": ["one_public_class_per_file", "multiple_classes_allowed", "no_rule"]
+    },
+    "type_contract_policy": {
+      "type": "string",
+      "enum": ["prefer_types_over_interfaces", "interfaces_everywhere", "interfaces_public_only"]
+    },
+    "mutability": {
+      "type": "string",
+      "enum": ["immutability_preferred", "immutability_strict", "mutable_pragmatic"]
+    },
+    "comment_section_blocks": {
+      "type": "array",
+      "minItems": 13,
+      "maxItems": 13,
+      "items": {
+        "type": "string",
+        "enum": [
+          "imports:externals",
+          "imports:internals",
+          "consts",
+          "types",
+          "private:attributes",
+          "private:properties",
+          "public:properties",
+          "constructor",
+          "static:properties",
+          "factory",
+          "private:methods",
+          "public:methods",
+          "static:methods"
+        ]
+      },
+      "const": [
+        "imports:externals",
+        "imports:internals",
+        "consts",
+        "types",
+        "private:attributes",
+        "private:properties",
+        "public:properties",
+        "constructor",
+        "static:properties",
+        "factory",
+        "private:methods",
+        "public:methods",
+        "static:methods"
+      ]
+    },
+    "comment_section_format": {
+      "type": "string",
+      "const": "jsdoc-section-tag"
+    },
+    "comment_sections_required_when_empty": {
+      "type": "boolean",
+      "const": true
+    },
+    "if_requires_braces": {
+      "type": "boolean",
+      "const": true
+    },
+    "readme_style": {
+      "type": "string",
+      "const": "top-tier"
+    },
+    "rule_severity_model": {
+      "type": "string",
+      "enum": ["all_blocking", "tiered", "all_preferred"]
+    },
+    "language": {
+      "type": "string",
+      "enum": ["english_technical", "spanish_technical", "bilingual"]
+    },
+    "examples_density": {
+      "type": "string",
+      "enum": ["rule_with_good_bad_examples", "rules_only", "rules_plus_long_templates"]
+    },
+    "instruction_file_location": {
+      "type": "string",
+      "enum": ["root_agents_md", "ai_instructions_md", "both"]
+    }
+  }
+}

package/resources/ai/AGENTS.md

@@ -0,0 +1,16 @@
+# AI Template System Entry Point
+
+This directory stores profile-aware templates used by `code-standards init`.
+
+Template resolution order:
+
+1. `resources/ai/templates/agents.project.template.md`
+2. `resources/ai/templates/rules/*.md`
+3. `resources/ai/templates/adapters/*.template.md`
+
+Rendering rules:
+
+- Render from validated profile data (`profiles/schema.json`).
+- Use deterministic token replacement.
+- Preserve stable section order in generated `AGENTS.md`.
+- Keep assistant adapters aligned with the generated project contract.

package/resources/ai/adapters/codex.md

@@ -0,0 +1,5 @@
+# Codex Adapter
+
+- Implement directly and keep changes minimal.
+- Prefer deterministic commands and explicit validation.
+- Use `npm run check` as the completion gate.

package/resources/ai/adapters/copilot.md

@@ -0,0 +1,5 @@
+# Copilot Adapter
+
+- Generate ESM-first TypeScript code.
+- Prefer small composable functions.
+- Add or update tests for behavioral changes.

package/resources/ai/adapters/cursor.md

@@ -0,0 +1,5 @@
+# Cursor Adapter
+
+- Use project-local configs as the primary source of style truth.
+- Avoid introducing structure that does not match `src/` and `test/` layout.
+- Validate with `npm run check`.

package/resources/ai/adapters/windsurf.md

@@ -0,0 +1,5 @@
+# Windsurf Adapter
+
+- Keep edits aligned with @sha3/code-standards exports.
+- Run local enforcement scripts instead of relying on remote CI.
+- Preserve assistant files (`AGENTS.md`, `ai/*.md`) unless explicitly removed by user.

package/resources/ai/templates/adapters/codex.template.md

@@ -0,0 +1,6 @@
+# Codex Adapter
+
+- Read `AGENTS.md` first and treat all rules as blocking.
+- Do not bypass the single-return policy.
+- Prefer class-based implementations with constructor injection.
+- Always run `npm run check` before finalizing changes.

package/resources/ai/templates/adapters/copilot.template.md

@@ -0,0 +1,6 @@
+# GitHub Copilot Adapter
+
+- Generate class-first code aligned with `AGENTS.md` rules.
+- Keep methods short and focused.
+- Use `async/await` only and typed errors for failure paths.
+- Include test updates for behavior changes.

package/resources/ai/templates/adapters/cursor.template.md

@@ -0,0 +1,6 @@
+# Cursor Adapter
+
+- Apply `AGENTS.md` as the highest-priority local instruction file.
+- Keep feature-folder organization intact.
+- Enforce single-return functions even during quick refactors.
+- Run `npm run check` after modifications.

package/resources/ai/templates/adapters/windsurf.template.md

@@ -0,0 +1,6 @@
+# Windsurf Adapter
+
+- Treat `AGENTS.md` as a mandatory contract.
+- Follow class-first and feature-folder conventions.
+- Avoid early returns; keep a single return per function.
+- Execute local deterministic checks with `npm run check`.

package/resources/ai/templates/agents.project.template.md

@@ -0,0 +1,33 @@
+# AI Coding Contract
+
+Project: {{projectName}}
+
+This file defines **blocking** rules for AI-generated code in this repository. Every rule below is mandatory.
+
+## Active Profile
+
+{{profileSummary}}
+
+## 1. Rule Hierarchy
+
+1. `AGENTS.md` (this file)
+2. Local project configs (`package.json`, `eslint.config.mjs`, `prettier.config.cjs`, `tsconfig.json`)
+3. Existing source code and tests
+
+If two rules conflict, the higher rule in this list MUST win.
+
+## 2. Code Generation Rules
+
+{{codeGenerationRules}}
+
+## 3. Architecture Rules
+
+{{architectureRules}}
+
+## 4. Testing and Review Rules
+
+{{testingReviewRules}}
+
+## 5. Assistant Execution Notes
+
+{{assistantExecutionNotes}}

package/resources/ai/templates/rules/architecture.md

@@ -0,0 +1,26 @@
+### Feature-Folder Architecture (MUST)
+
+- Code MUST be organized by feature (for example: `src/users`, `src/billing`, `src/invoices`).
+- Each feature MUST keep its own domain model, application services, and infrastructure adapters grouped by feature.
+- Cross-feature imports MUST happen through explicit public entry points.
+
+Good example:
+
+```text
+src/
+  invoices/
+    invoice-service.ts
+    invoice-repository.ts
+    invoice-types.ts
+  billing/
+    billing-service.ts
+```
+
+Bad example:
+
+```text
+src/
+  services/
+  repositories/
+  models/
+```

package/resources/ai/templates/rules/async.md

@@ -0,0 +1,23 @@
+### Async Policy (MUST)
+
+- Asynchronous code MUST use `async/await`.
+- `.then()`/`.catch()` chains are not allowed for new code.
+- Every async call chain MUST have explicit error handling at the boundary.
+
+Good example:
+
+```ts
+public async execute(command: SyncInvoicesCommand): Promise<SyncResult> {
+  const invoices: Invoice[] = await this.source.fetch(command.accountId);
+  const result: SyncResult = await this.writer.persist(invoices);
+  return result;
+}
+```
+
+Bad example:
+
+```ts
+public execute(command: SyncInvoicesCommand): Promise<SyncResult> {
+  return this.source.fetch(command.accountId).then((invoices) => this.writer.persist(invoices));
+}
+```

package/resources/ai/templates/rules/class-first.md

@@ -0,0 +1,96 @@
+### Class-First Design (MUST)
+
+- New business/domain logic MUST be modeled with classes by default.
+- Each class MUST use constructor injection for dependencies.
+- A source file MUST expose one public class.
+- Mutable shared state MUST be avoided; prefer `readonly` fields and deterministic methods.
+- Class-oriented files MUST always include all section comment blocks using this exact format:
+  - `/** @section imports:externals */`
+  - `/** @section imports:internals */`
+  - `/** @section consts */`
+  - `/** @section types */`
+  - `/** @section private:attributes */`
+  - `/** @section private:properties */`
+  - `/** @section public:properties */`
+  - `/** @section constructor */`
+  - `/** @section static:properties */`
+  - `/** @section factory */`
+  - `/** @section private:methods */`
+  - `/** @section public:methods */`
+  - `/** @section static:methods */`
+- All section blocks MUST exist even when empty, using `// empty` after the section marker.
+- `factory` MUST only contain methods that create and return instances of the same class.
+
+Good example:
+
+```ts
+/** @section imports:externals */
+import { randomUUID } from "node:crypto";
+
+/** @section imports:internals */
+import type { InvoiceRepository } from "./invoice-repository.js";
+import type { CreateInvoiceCommand, Invoice } from "./invoice-types.js";
+
+/** @section consts */
+const SERVICE_NAME = "invoice-service";
+
+/** @section types */
+type InvoiceDraft = { customerId: string; amount: number };
+
+export class InvoiceService {
+  /** @section private:attributes */
+  private readonly requestId: string;
+
+  /** @section private:properties */
+  private readonly repository: InvoiceRepository;
+
+  /** @section public:properties */
+  public readonly serviceName: string;
+
+  /** @section constructor */
+  public constructor(repository: InvoiceRepository) {
+    this.repository = repository;
+    this.requestId = randomUUID();
+    this.serviceName = SERVICE_NAME;
+  }
+
+  /** @section static:properties */
+  // empty
+
+  /** @section factory */
+  public static create(repository: InvoiceRepository): InvoiceService {
+    const service = new InvoiceService(repository);
+    return service;
+  }
+
+  /** @section private:methods */
+  private toInvoiceDraft(command: CreateInvoiceCommand): InvoiceDraft {
+    const draft: InvoiceDraft = { customerId: command.customerId, amount: command.amount };
+    return draft;
+  }
+
+  /** @section public:methods */
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    const draft: InvoiceDraft = this.toInvoiceDraft(command);
+    const invoice: Invoice = await this.repository.save(draft);
+    return invoice;
+  }
+
+  /** @section static:methods */
+  // empty
+}
+```
+
+Bad example:
+
+```ts
+import { randomUUID } from "node:crypto";
+
+export class InvoiceService {
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    const repository = new InvoiceRepository();
+    if (!command.customerId) return Promise.reject(new Error("invalid"));
+    return repository.save(command as any);
+  }
+}
+```

package/resources/ai/templates/rules/control-flow.md

@@ -0,0 +1,19 @@
+### Control Flow Braces (MUST)
+
+- `if`, `else if`, `else`, `for`, `while`, and `do` blocks MUST always use braces.
+- Single-line `if` statements without braces are forbidden.
+- This rule applies even when the body has one statement.
+
+Good example:
+
+```ts
+if (isEnabled) {
+  executeTask();
+}
+```
+
+Bad example:
+
+```ts
+if (isEnabled) executeTask();
+```

package/resources/ai/templates/rules/errors.md

@@ -0,0 +1,22 @@
+### Error Handling (MUST)
+
+- Domain/application errors MUST use explicit typed error classes.
+- Errors MUST be thrown and handled at clear application boundaries.
+- Error messages MUST include actionable context.
+
+Good example:
+
+```ts
+export class InvoiceNotFoundError extends Error {
+  public constructor(invoiceId: string) {
+    super(`Invoice not found: ${invoiceId}`);
+    this.name = "InvoiceNotFoundError";
+  }
+}
+```
+
+Bad example:
+
+```ts
+throw new Error("Oops");
+```