@sha3/code-standards 0.1.1 → 0.1.2

package/resources/ai/templates/examples/rules/testing-bad.ts

@@ -0,0 +1,88 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+// empty
+
+/**
+ * @section types
+ */
+
+type Invoice = { issuedAt: Date };
+
+export class InvoiceEscalationPolicy {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  // empty
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  // empty
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceEscalationPolicy {
+    const policy = new InvoiceEscalationPolicy();
+    return policy;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  // empty
+
+  /**
+   * @section public:methods
+   */
+
+  public evaluateEscalation(invoice: Invoice, now: Date): Promise<string> {
+    return Promise.resolve(invoice).then((current: Invoice) => {
+      const hasAge = now.getTime() - current.issuedAt.getTime() > 0;
+      const decision = hasAge ? "x" : "y";
+      return decision;
+    });
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/testing-good.ts

@@ -0,0 +1,92 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * @section types
+ */
+
+type Invoice = { issuedAt: Date };
+type EscalationDecision = "manual-review" | "no-escalation";
+
+export class InvoiceEscalationPolicy {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  // empty
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  // empty
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceEscalationPolicy {
+    const policy = new InvoiceEscalationPolicy();
+    return policy;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private daysBetween(from: Date, to: Date): number {
+    const diffInMilliseconds = to.getTime() - from.getTime();
+    const dayCount = Math.floor(diffInMilliseconds / MILLISECONDS_PER_DAY);
+    return dayCount;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  // Business rule: invoices older than 30 days are escalated for manual review.
+  public evaluateEscalation(invoice: Invoice, now: Date): EscalationDecision {
+    const ageInDays: number = this.daysBetween(invoice.issuedAt, now);
+    const decision: EscalationDecision = ageInDays > 30 ? "manual-review" : "no-escalation";
+    return decision;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -6,21 +6,11 @@
 
 Good example:
 
-```text
-src/
-  invoices/
-    invoice-service.ts
-    invoice-repository.ts
-    invoice-types.ts
-  billing/
-    billing-service.ts
-```
+- `ai/examples/demo/src/invoices/invoice-service.ts`
+- `ai/examples/demo/src/invoices/invoice-errors.ts`
+- `ai/examples/demo/src/invoices/invoice-types.ts`
+- `ai/examples/demo/src/billing/billing-service.ts`
 
 Bad example:
 
-```text
-src/
-  services/
-  repositories/
-  models/
-```
+- `ai/examples/rules/class-first-bad.ts` (mixes concerns and does not keep feature boundaries)

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

@@ -6,18 +6,8 @@
 
 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;
-}
-```
+- `ai/examples/rules/async-good.ts`
 
 Bad example:
 
-```ts
-public execute(command: SyncInvoicesCommand): Promise<SyncResult> {
-  return this.source.fetch(command.accountId).then((invoices) => this.writer.persist(invoices));
-}
-```
+- `ai/examples/rules/async-bad.ts`

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

@@ -4,93 +4,34 @@
 - 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 */`
+- Class-oriented files MUST always include all section comment blocks using this exact 3-line format:
+  - `/**`
+  - ` * @section <block-name>`
+  - ` */`
+- Required section block names (in order):
+  - `imports:externals`
+  - `imports:internals`
+  - `consts`
+  - `types`
+  - `private:attributes`
+  - `private:properties`
+  - `public:properties`
+  - `constructor`
+  - `static:properties`
+  - `factory`
+  - `private:methods`
+  - `public:methods`
+  - `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
-}
-```
+- `ai/examples/rules/class-first-good.ts`
+- `ai/examples/rules/constructor-good.ts`
+- `ai/examples/demo/src/invoices/invoice-service.ts`
 
 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);
-  }
-}
-```
+- `ai/examples/rules/class-first-bad.ts`
+- `ai/examples/rules/constructor-bad.ts`

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

@@ -6,14 +6,8 @@
 
 Good example:
 
-```ts
-if (isEnabled) {
-  executeTask();
-}
-```
+- `ai/examples/rules/control-flow-good.ts`
 
 Bad example:
 
-```ts
-if (isEnabled) executeTask();
-```
+- `ai/examples/rules/control-flow-bad.ts`

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

@@ -6,17 +6,8 @@
 
 Good example:
 
-```ts
-export class InvoiceNotFoundError extends Error {
-  public constructor(invoiceId: string) {
-    super(`Invoice not found: ${invoiceId}`);
-    this.name = "InvoiceNotFoundError";
-  }
-}
-```
+- `ai/examples/rules/errors-good.ts`
 
 Bad example:
 
-```ts
-throw new Error("Oops");
-```
+- `ai/examples/rules/errors-bad.ts`

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

@@ -7,21 +7,8 @@
 
 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 };
-}
-```
+- `ai/examples/rules/functions-good.ts`
 
 Bad example:
 
-```ts
-private normalize(input: any): any {
-  // huge branchy function with parsing, IO, validation and persistence mixed together
-  // ... 80+ lines omitted
-  return input;
-}
-```
+- `ai/examples/rules/functions-bad.ts`

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

@@ -6,28 +6,8 @@
 
 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;
-}
-```
+- `ai/examples/rules/returns-good.ts`
 
 Bad example:
 
-```ts
-public toStatusLabel(status: InvoiceStatus): string {
-  if (status === "paid") return "Paid";
-  if (status === "void") return "Void";
-  return "Pending";
-}
-```
+- `ai/examples/rules/returns-bad.ts`

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

@@ -7,20 +7,8 @@
 
 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;
-}
-```
+- `ai/examples/rules/testing-good.ts`
 
 Bad example:
 
-```ts
-public evaluateEscalation(invoice: any, now: Date): any {
-  return Promise.resolve(invoice).then((it) => (Date.now() - it.issuedAt > 0 ? "x" : "y"));
-}
-```
+- `ai/examples/rules/testing-bad.ts`

package/standards/style.md

@@ -25,7 +25,15 @@ All code MUST follow the canonical rules in `standards/manifest.json`.
 
 ## Class File Comment Blocks
 
-Class-oriented files MUST use `/** @section ... */` markers in this exact order:
+Class-oriented files MUST use 3-line JSDoc section markers in this exact order:
+
+```ts
+/**
+ * @section <block-name>
+ */
+```
+
+Required block names:
 
 1. `imports:externals`
 2. `imports:internals`

package/templates/node-lib/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.DS_Store

package/templates/node-service/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.DS_Store