@sha3/code-standards 0.1.0

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

@@ -0,0 +1,27 @@
+### Function Structure (MUST)
+
+- Functions and methods SHOULD stay under 30 lines.
+- Functions MUST implement one responsibility.
+- Long functions MUST be split into private helper methods.
+- Types MUST be preferred over interfaces for local modeling unless a public contract requires an interface.
+
+Good example:
+
+```ts
+private normalize(input: PaymentInput): PaymentDraft {
+  const amount: number = normalizeAmount(input.amount);
+  const currency: CurrencyCode = normalizeCurrency(input.currency);
+  const metadata: PaymentMetadata = sanitizeMetadata(input.metadata);
+  return { amount, currency, metadata };
+}
+```
+
+Bad example:
+
+```ts
+private normalize(input: any): any {
+  // huge branchy function with parsing, IO, validation and persistence mixed together
+  // ... 80+ lines omitted
+  return input;
+}
+```

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

@@ -0,0 +1,25 @@
+### README Quality Standard (MUST)
+
+When creating or updating `README.md`, output MUST be top-tier and production-quality.
+
+Mandatory requirements:
+
+- README MUST clearly explain: what the project does, why it exists, and how to use it in under 60 seconds.
+- README MUST include practical copy/paste examples that are runnable.
+- README MUST include a fast path (`TL;DR` or `Quick Start`) and an in-depth reference section.
+- README MUST include a section for AI usage (how to instruct assistants to follow local standards).
+- README MUST avoid vague marketing language and focus on actionable guidance.
+- README MUST be visually structured with clean headings, concise lists, and code blocks.
+- README MUST be updated whenever behavior, commands, or setup steps change.
+
+Good example characteristics:
+
+- Starts with immediate value and one-command quick start.
+- Shows exact commands and expected flow.
+- Includes troubleshooting or FAQ for common confusion points.
+
+Bad example characteristics:
+
+- Only describes high-level ideas.
+- Missing runnable commands.
+- Forces reader to guess execution order.

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

@@ -0,0 +1,33 @@
+### Return Policy (MUST)
+
+- Every function or method MUST have a single `return` statement.
+- Early returns are not allowed.
+- Conditional paths MUST assign to a local result variable and return once.
+
+Good example:
+
+```ts
+public toStatusLabel(status: InvoiceStatus): string {
+  let label: string;
+
+  if (status === "paid") {
+    label = "Paid";
+  } else if (status === "void") {
+    label = "Void";
+  } else {
+    label = "Pending";
+  }
+
+  return label;
+}
+```
+
+Bad example:
+
+```ts
+public toStatusLabel(status: InvoiceStatus): string {
+  if (status === "paid") return "Paid";
+  if (status === "void") return "Void";
+  return "Pending";
+}
+```

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

@@ -0,0 +1,26 @@
+### Testing and Comments (MUST)
+
+- Any behavior change MUST include or update tests.
+- Tests MUST validate behavior, not implementation details.
+- Comments MUST be explicit and extensive when logic is non-trivial.
+- Async workflows MUST use `async/await` style only.
+
+Good example:
+
+```ts
+// Business rule: invoices older than 30 days are escalated for manual review.
+public evaluateEscalation(invoice: Invoice, now: Date): EscalationDecision {
+  const ageInDays: number = daysBetween(invoice.issuedAt, now);
+  const decision: EscalationDecision =
+    ageInDays > 30 ? "manual-review" : "no-escalation";
+  return decision;
+}
+```
+
+Bad example:
+
+```ts
+public evaluateEscalation(invoice: any, now: Date): any {
+  return Promise.resolve(invoice).then((it) => (Date.now() - it.issuedAt > 0 ? "x" : "y"));
+}
+```

package/standards/architecture.md

@@ -0,0 +1,24 @@
+# Architecture Guide
+
+Architecture strictness is **moderate**.
+
+## Project Templates
+
+Two templates are supported:
+
+- `node-lib`
+- `node-service`
+
+## Default Layout
+
+Both templates SHOULD keep this baseline structure:
+
+- `src/` for implementation.
+- `test/` for automated tests.
+- `eslint.config.mjs`, `prettier.config.cjs`, and `tsconfig.json` at root.
+
+## Boundary Rules
+
+- Keep feature modules cohesive.
+- Avoid cyclic dependencies.
+- Keep configuration centralized at project root.

package/standards/changelog-policy.md

@@ -0,0 +1,12 @@
+# Changelog Policy
+
+## Versioning
+
+Use semantic versioning for the published `@sha3/code-standards` package.
+
+## Rules
+
+- Every release MUST include a concise changelog entry.
+- Breaking changes MUST document migration steps.
+- `npm run release:check` MUST pass before publishing.
+- Use `npm run release:publish` to publish from repository root.

package/standards/manifest.json

@@ -0,0 +1,47 @@
+{
+  "meta": {
+    "version": "v1",
+    "scope": "@sha3",
+    "packageManager": "npm",
+    "moduleSystem": "esm"
+  },
+  "language": {
+    "runtime": "node",
+    "typescript": true,
+    "target": "ES2022"
+  },
+  "formatting": {
+    "prettier": true,
+    "lineLength": 100,
+    "semi": true,
+    "singleQuote": false
+  },
+  "naming": {
+    "files": "kebab-case",
+    "directories": "kebab-case",
+    "typescript": {
+      "types": "PascalCase",
+      "interfaces": "PascalCase",
+      "constants": "SCREAMING_SNAKE_CASE"
+    }
+  },
+  "architecture": {
+    "strictness": "moderate",
+    "templates": ["node-lib", "node-service"]
+  },
+  "testing": {
+    "runner": "node-test-runner",
+    "coverage": false,
+    "testLocation": "test/"
+  },
+  "tooling": {
+    "eslintConfig": "@sha3/code-standards/eslint/node",
+    "prettierConfig": "@sha3/code-standards/prettier",
+    "tsconfigPackage": "@sha3/code-standards/tsconfig/node-lib.json",
+    "enforcement": "local-strict"
+  },
+  "ai": {
+    "enabledByDefault": true,
+    "assistants": ["codex", "cursor", "copilot", "windsurf"]
+  }
+}

package/standards/readme.md

@@ -0,0 +1,25 @@
+# README Guide
+
+## Goal
+
+Every repository README MUST be clear, actionable, and visually structured.
+
+## Mandatory Sections
+
+- Title and one-line value proposition.
+- TL;DR or Quick Start with copy/paste commands.
+- What it does and why it exists.
+- Setup and usage examples.
+- AI workflow section when the repository uses AI coding contracts.
+- Troubleshooting or FAQ.
+
+## Writing Rules
+
+- Use concrete commands and expected execution order.
+- Avoid vague claims without implementation detail.
+- Keep headings and lists scannable.
+- Update README with every behavior or command change.
+
+## Quality Bar
+
+A top-tier README lets a new engineer understand and run the project in under 5 minutes without asking additional questions.

package/standards/schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sha3.dev/code-standards/schema.json",
+  "title": "Code Standards Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "meta",
+    "language",
+    "formatting",
+    "naming",
+    "architecture",
+    "testing",
+    "tooling",
+    "ai"
+  ],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "scope", "packageManager", "moduleSystem"],
+      "properties": {
+        "version": { "type": "string", "pattern": "^v[0-9]+$" },
+        "scope": { "type": "string", "const": "@sha3" },
+        "packageManager": { "type": "string", "const": "npm" },
+        "moduleSystem": { "type": "string", "enum": ["esm"] }
+      }
+    },
+    "language": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtime", "typescript", "target"],
+      "properties": {
+        "runtime": { "type": "string", "const": "node" },
+        "typescript": { "type": "boolean" },
+        "target": { "type": "string" }
+      }
+    },
+    "formatting": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prettier", "lineLength", "semi", "singleQuote"],
+      "properties": {
+        "prettier": { "type": "boolean" },
+        "lineLength": { "type": "integer", "minimum": 80, "maximum": 140 },
+        "semi": { "type": "boolean" },
+        "singleQuote": { "type": "boolean" }
+      }
+    },
+    "naming": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["files", "directories", "typescript"],
+      "properties": {
+        "files": { "type": "string", "enum": ["kebab-case"] },
+        "directories": { "type": "string", "enum": ["kebab-case"] },
+        "typescript": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["types", "interfaces", "constants"],
+          "properties": {
+            "types": { "type": "string", "enum": ["PascalCase"] },
+            "interfaces": { "type": "string", "enum": ["PascalCase"] },
+            "constants": { "type": "string", "enum": ["SCREAMING_SNAKE_CASE"] }
+          }
+        }
+      }
+    },
+    "architecture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strictness", "templates"],
+      "properties": {
+        "strictness": { "type": "string", "enum": ["moderate"] },
+        "templates": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["node-lib", "node-service"] },
+          "minItems": 2,
+          "uniqueItems": true
+        }
+      }
+    },
+    "testing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runner", "coverage", "testLocation"],
+      "properties": {
+        "runner": { "type": "string", "const": "node-test-runner" },
+        "coverage": { "type": "boolean" },
+        "testLocation": { "type": "string", "enum": ["test/"] }
+      }
+    },
+    "tooling": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["eslintConfig", "prettierConfig", "tsconfigPackage", "enforcement"],
+      "properties": {
+        "eslintConfig": { "type": "string", "const": "@sha3/code-standards/eslint/node" },
+        "prettierConfig": { "type": "string", "const": "@sha3/code-standards/prettier" },
+        "tsconfigPackage": {
+          "type": "string",
+          "const": "@sha3/code-standards/tsconfig/node-lib.json"
+        },
+        "enforcement": { "type": "string", "enum": ["local-strict"] }
+      }
+    },
+    "ai": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabledByDefault", "assistants"],
+      "properties": {
+        "enabledByDefault": { "type": "boolean" },
+        "assistants": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["codex", "cursor", "copilot", "windsurf"] },
+          "minItems": 4,
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/standards/style.md

@@ -0,0 +1,48 @@
+# Style Guide
+
+All code MUST follow the canonical rules in `standards/manifest.json`.
+
+## Formatting
+
+- Use Prettier for formatting.
+- Use a max line length of 100.
+- Use semicolons.
+- Use double quotes for strings.
+
+## TypeScript
+
+- Use strict TypeScript mode.
+- Avoid `any` unless there is no viable alternative.
+- Prefer explicit return types for exported functions.
+- Use type-only imports when possible.
+- Always use braces in control flow (`if`, `else`, `for`, `while`, `do`).
+
+## Naming
+
+- Use `kebab-case` for files and directories.
+- Use `PascalCase` for types and interfaces.
+- Use `SCREAMING_SNAKE_CASE` for constants.
+
+## Class File Comment Blocks
+
+Class-oriented files MUST use `/** @section ... */` markers in this exact order:
+
+1. `imports:externals`
+2. `imports:internals`
+3. `consts`
+4. `types`
+5. `private:attributes`
+6. `private:properties`
+7. `public:properties`
+8. `constructor`
+9. `static:properties`
+10. `factory`
+11. `private:methods`
+12. `public:methods`
+13. `static:methods`
+
+All section blocks MUST be present even when empty. Empty sections MUST include:
+
+```ts
+// empty
+```

package/standards/testing.md

@@ -0,0 +1,18 @@
+# Testing Guide
+
+Projects MUST use the Node test runner.
+
+## Location
+
+- Store tests under `test/`.
+- Use `*.test.ts` or `*.test.js` naming.
+
+## Commands
+
+- `npm run test` MUST execute all automated tests.
+- `npm run check` MUST include test execution.
+
+## Assertions
+
+- Prefer `node:assert/strict`.
+- Keep tests deterministic and isolated.

package/standards/tooling.md

@@ -0,0 +1,32 @@
+# Tooling Guide
+
+All new projects MUST use this package and its subpath exports:
+
+- `@sha3/code-standards/eslint/node`
+- `@sha3/code-standards/eslint/test`
+- `@sha3/code-standards/prettier`
+- `@sha3/code-standards/tsconfig/node-lib.json` or `node-service.json`
+
+## Behavioral Policy
+
+In addition to tooling, each generated project MUST include profile-driven AI instructions:
+
+- `AGENTS.md` generated from the active style profile
+- `ai/codex.md`, `ai/cursor.md`, `ai/copilot.md`, `ai/windsurf.md`
+
+The generated instructions are blocking rules and MUST be treated as the top local AI coding contract.
+
+## Enforcement
+
+Enforcement is local and strict.
+
+Required scripts:
+
+- `npm run check`
+- `npm run fix`
+- `npm run lint`
+- `npm run format:check`
+- `npm run typecheck`
+- `npm run test`
+
+No remote CI is required for v1.

package/templates/node-lib/eslint.config.mjs

@@ -0,0 +1,4 @@
+import nodeConfig from "@sha3/code-standards/eslint/node";
+import testConfig from "@sha3/code-standards/eslint/test";
+
+export default [...nodeConfig, ...testConfig];

package/templates/node-lib/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run test",
+    "fix": "npm run lint:fix && npm run format:write",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format:check": "prettier --check .",
+    "format:write": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test"
+  },
+  "devDependencies": {
+    "@sha3/code-standards": "^0.1.0",
+    "@types/node": "^22.13.10",
+    "eslint": "^9.20.1",
+    "prettier": "^3.5.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/templates/node-lib/prettier.config.cjs

@@ -0,0 +1,9 @@
+let config;
+
+try {
+  config = require("@sha3/code-standards/prettier");
+} catch {
+  config = require("../../prettier/index.cjs");
+}
+
+module.exports = config;

package/templates/node-lib/src/index.ts

@@ -0,0 +1,3 @@
+export function greet(name: string): string {
+  return `Hello, ${name}`;
+}

package/templates/node-lib/test/smoke.test.ts

@@ -0,0 +1,8 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { greet } from "../src/index.js";
+
+test("greet returns a deterministic message", () => {
+  assert.equal(greet("world"), "Hello, world");
+});

package/templates/node-lib/tsconfig.build.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false
+  },
+  "exclude": ["test/**/*.ts"]
+}

package/templates/node-lib/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@sha3/code-standards/tsconfig/node-lib.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/templates/node-service/eslint.config.mjs

@@ -0,0 +1,4 @@
+import nodeConfig from "@sha3/code-standards/eslint/node";
+import testConfig from "@sha3/code-standards/eslint/test";
+
+export default [...nodeConfig, ...testConfig];

package/templates/node-service/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node --import tsx src/index.ts",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run test",
+    "fix": "npm run lint:fix && npm run format:write",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format:check": "prettier --check .",
+    "format:write": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test"
+  },
+  "devDependencies": {
+    "@sha3/code-standards": "^0.1.0",
+    "@types/node": "^22.13.10",
+    "eslint": "^9.20.1",
+    "prettier": "^3.5.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/templates/node-service/prettier.config.cjs

@@ -0,0 +1,9 @@
+let config;
+
+try {
+  config = require("@sha3/code-standards/prettier");
+} catch {
+  config = require("../../prettier/index.cjs");
+}
+
+module.exports = config;

package/templates/node-service/src/index.ts

@@ -0,0 +1,17 @@
+import { createServer } from "node:http";
+
+export function buildServer() {
+  return createServer((_, response) => {
+    response.statusCode = 200;
+    response.setHeader("content-type", "application/json");
+    response.end(JSON.stringify({ ok: true }));
+  });
+}
+
+if (process.env.NODE_ENV !== "test") {
+  const port = Number(process.env.PORT ?? "3000");
+  const server = buildServer();
+  server.listen(port, () => {
+    console.log(`service listening on http://localhost:${port}`);
+  });
+}

package/templates/node-service/test/smoke.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildServer } from "../src/index.js";
+
+test("service responds with ok payload", async () => {
+  const server = buildServer();
+
+  await new Promise<void>((resolve) => {
+    server.listen(0, () => {
+      resolve();
+    });
+  });
+
+  const address = server.address();
+
+  if (!address || typeof address === "string") {
+    throw new Error("failed to bind test server");
+  }
+
+  const response = await fetch(`http://127.0.0.1:${address.port}`);
+  const json = await response.json();
+
+  assert.equal(response.status, 200);
+  assert.deepEqual(json, { ok: true });
+
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      resolve();
+    });
+  });
+});

package/templates/node-service/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@sha3/code-standards/tsconfig/node-service.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/tsconfig/base.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "isolatedModules": true,
+    "esModuleInterop": false,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}

package/tsconfig/node-lib.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}