@sha3/code 1.0.0

package/resources/ai/templates/examples/rules/class-first-good.ts

@@ -0,0 +1,74 @@
+/**
+ * @section imports:externals
+ */
+
+import { randomUUID } from "node:crypto";
+
+/**
+ * @section consts
+ */
+
+const serviceName = "invoice-service";
+
+/**
+ * @section types
+ */
+
+type CreateInvoiceCommand = { customerId: string; amount: number };
+type Invoice = { id: string; customerId: string; amount: number; createdAt: Date };
+
+/**
+ * @section class
+ */
+export class InvoiceService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly requestId: string;
+  private readonly invoicesById: Map<string, Invoice>;
+
+  /**
+   * @section public:properties
+   */
+
+  public readonly serviceName: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor() {
+    this.requestId = randomUUID();
+    this.invoicesById = new Map<string, Invoice>();
+    this.serviceName = serviceName;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceService {
+    const service = new InvoiceService();
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private toInvoice(command: CreateInvoiceCommand): Invoice {
+    const invoice: Invoice = { id: randomUUID(), customerId: command.customerId, amount: command.amount, createdAt: new Date() };
+    return invoice;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    const invoice: Invoice = this.toInvoice(command);
+    this.invoicesById.set(invoice.id, invoice);
+    return invoice;
+  }
+}

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

@@ -0,0 +1,68 @@
+/**
+ * @section consts
+ */
+
+const fallbackPrefix = "INV";
+
+/**
+ * @section types
+ */
+
+type Clock = () => Date;
+type IdFactory = () => string;
+
+export class InvoiceIdBuilder {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly clock: Clock;
+  private readonly idFactory: IdFactory;
+  private readonly prefix: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor() {
+    // Bad: constructor wires concrete dependencies and environment details directly.
+    this.clock = () => new Date();
+    this.idFactory = () => Math.random().toString(36).slice(2, 8);
+    this.prefix = process.env.INVOICE_PREFIX || fallbackPrefix;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceIdBuilder {
+    const builder = new InvoiceIdBuilder();
+    return builder;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private currentYear(): number {
+    const year = this.clock().getUTCFullYear();
+    return year;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public build(): string {
+    const rawId = this.idFactory();
+    const year = this.currentYear();
+    const invoiceId = `${this.prefix}-${year}-${rawId}`;
+    return invoiceId;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @section consts
+ */
+
+const defaultInvoicePrefix = "INV";
+
+/**
+ * @section types
+ */
+
+type Clock = () => Date;
+type IdFactory = () => string;
+
+/**
+ * @section class
+ */
+
+export class InvoiceIdBuilder {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly clock: Clock;
+  private readonly idFactory: IdFactory;
+  private readonly prefix: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(clock: Clock, idFactory: IdFactory, prefix = defaultInvoicePrefix) {
+    this.clock = clock;
+    this.idFactory = idFactory;
+    this.prefix = prefix;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(clock: Clock, idFactory: IdFactory): InvoiceIdBuilder {
+    const builder = new InvoiceIdBuilder(clock, idFactory);
+    return builder;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private currentYear(): number {
+    const year = this.clock().getUTCFullYear();
+    return year;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public build(): string {
+    const rawId = this.idFactory();
+    const year = this.currentYear();
+    const invoiceId = `${this.prefix}-${year}-${rawId}`;
+    return invoiceId;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/control-flow-bad.ts

@@ -0,0 +1,31 @@
+/**
+ * @section types
+ */
+
+// empty
+
+export class ControlFlowPolicy {
+  /**
+   * @section factory
+   */
+
+  public static create(): ControlFlowPolicy {
+    const policy = new ControlFlowPolicy();
+    return policy;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public badSnippet(): string {
+    const snippet = "if (isEnabled) executeTask();";
+    return snippet;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/control-flow-good.ts

@@ -0,0 +1,54 @@
+/**
+ * @section types
+ */
+
+type FeatureFlagMap = Record<string, boolean>;
+
+/**
+ * @section class
+ */
+
+export class FeatureGate {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly flags: FeatureFlagMap;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(flags: FeatureFlagMap) {
+    this.flags = flags;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static from(flags: FeatureFlagMap): FeatureGate {
+    const gate = new FeatureGate(flags);
+    return gate;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public canRunTask(key: string): boolean {
+    let enabled = false;
+
+    if (this.flags[key] === true) {
+      enabled = true;
+    }
+
+    return enabled;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,42 @@
+/**
+ * @section types
+ */
+
+// empty
+
+export class InvoiceLookup {
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceLookup {
+    const lookup = new InvoiceLookup();
+    return lookup;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public ensureInvoiceExists(invoiceId: string, exists: boolean): void {
+    try {
+      if (!exists) {
+        throw "missing";
+      }
+    } catch {
+      // bad: error is silently swallowed
+    }
+
+    if (!exists) {
+      throw new Error("failed");
+    }
+
+    console.log(invoiceId);
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @section class
+ */
+export class InvoiceLookup {
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceLookup {
+    const lookup = new InvoiceLookup();
+    return lookup;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public ensureInvoiceExists(invoiceId: string, exists: boolean): void {
+    if (!exists) {
+      throw new Error(`Invoice not found: invoiceId=${invoiceId}`);
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @section types
+ */
+
+type PaymentInput = { amount?: number; currency?: string; metadata?: Record<string, string> };
+type PersistedPaymentInput = PaymentInput & { normalizedAt: number; saved: boolean };
+
+export class PaymentNormalizer {
+  /**
+   * @section factory
+   */
+
+  public static create(): PaymentNormalizer {
+    const normalizer = new PaymentNormalizer();
+    return normalizer;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public normalize(input: PaymentInput): PersistedPaymentInput {
+    // Bad: too many responsibilities in one method.
+    const clone = { ...input };
+
+    if (!clone.currency) {
+      clone.currency = "usd";
+    }
+
+    if (typeof clone.currency === "string") {
+      clone.currency = clone.currency.toUpperCase();
+    }
+
+    if (!clone.metadata) {
+      clone.metadata = {};
+    }
+
+    clone.amount = Number(clone.amount || 0);
+    const persisted: PersistedPaymentInput = { ...clone, normalizedAt: Date.now(), saved: true };
+    return persisted;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,58 @@
+/**
+ * @section types
+ */
+
+type PaymentInput = { amount: number; currency: string; metadata: Record<string, string> };
+type PaymentDraft = { amount: number; currency: string; metadata: Record<string, string> };
+
+/**
+ * @section class
+ */
+
+export class PaymentNormalizer {
+  /**
+   * @section factory
+   */
+
+  public static create(): PaymentNormalizer {
+    const normalizer = new PaymentNormalizer();
+    return normalizer;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private normalizeAmount(amount: number): number {
+    const normalizedAmount = Number(amount.toFixed(2));
+    return normalizedAmount;
+  }
+
+  private normalizeCurrency(currency: string): string {
+    const normalizedCurrency = currency.trim().toUpperCase();
+    return normalizedCurrency;
+  }
+
+  private sanitizeMetadata(metadata: Record<string, string>): Record<string, string> {
+    const sanitizedMetadata: Record<string, string> = { ...metadata };
+    return sanitizedMetadata;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public normalize(input: PaymentInput): PaymentDraft {
+    const amount: number = this.normalizeAmount(input.amount);
+    const currency: string = this.normalizeCurrency(input.currency);
+    const metadata: Record<string, string> = this.sanitizeMetadata(input.metadata);
+    const draft: PaymentDraft = { amount, currency, metadata };
+    return draft;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,38 @@
+/**
+ * @section types
+ */
+
+type InvoiceStatus = "paid" | "void" | "pending";
+
+export class InvoiceStatusPresenter {
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceStatusPresenter {
+    const presenter = new InvoiceStatusPresenter();
+    return presenter;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public toStatusLabel(status: InvoiceStatus): string {
+    if (status === "paid") {
+      return "Paid";
+    }
+
+    if (status === "void") {
+      return "Void";
+    }
+
+    return "Pending";
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,44 @@
+/**
+ * @section types
+ */
+
+type InvoiceStatus = "paid" | "void" | "pending";
+
+/**
+ * @section class
+ */
+
+export class InvoiceStatusPresenter {
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceStatusPresenter {
+    const presenter = new InvoiceStatusPresenter();
+    return presenter;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public toStatusLabel(status: InvoiceStatus): string {
+    let label: string;
+
+    if (status === "paid") {
+      label = "Paid";
+    } else if (status === "void") {
+      label = "Void";
+    } else {
+      label = "Pending";
+    }
+
+    return label;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @section types
+ */
+
+type Invoice = { issuedAt: Date };
+
+export class InvoiceEscalationPolicy {
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceEscalationPolicy {
+    const policy = new InvoiceEscalationPolicy();
+    return policy;
+  }
+
+  /**
+   * @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,54 @@
+/**
+ * @section consts
+ */
+
+const millisecondsPerDay = 24 * 60 * 60 * 1000;
+
+/**
+ * @section types
+ */
+
+type Invoice = { issuedAt: Date };
+type EscalationDecision = "manual-review" | "no-escalation";
+
+/**
+ * @section class
+ */
+
+export class InvoiceEscalationPolicy {
+  /**
+   * @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 / millisecondsPerDay);
+    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

@@ -0,0 +1,41 @@
+### Feature-Folder Architecture (MUST)
+
+- Code MUST be organized by feature (for example: `src/user`, `src/billing`, `src/invoice`).
+- Feature folder names MUST be singular.
+- 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.
+- `src/` MUST stay feature-first with `src/index.ts` and `src/<feature>/`.
+- `src/app/` MUST exist only when the project has explicit composition/wiring that justifies it.
+- `src/shared/` MUST exist only when cross-feature modules actually exist.
+- Project layout MUST include `src/`, `test/`, `scripts/`, `docs/`, and `ai/` at minimum.
+- For `node-service`, HTTP transport concerns SHOULD live in `src/http/` (`routes`, `controllers`, `middleware`).
+- If a service needs to expose an HTTP API, it MUST use the latest published `hono` release line as the HTTP framework.
+- For `node-lib`, API boundary separation MAY use `src/public/` and `src/internal/`.
+- Feature files SHOULD use explicit role suffixes (`*.service.ts`, `*.repository.ts`, `*.schema.ts`, `*.mapper.ts`).
+- Use `*.types.ts` only when shared feature types are substantial enough to justify a dedicated file.
+- Inside `src/<feature>/`, files MUST expose exactly one public class unless the file is `*.types.ts`.
+- Feature file domain base names SHOULD be singular (for example: `invoice.service.ts`).
+- Ambiguous filenames (`utils.ts`, `helpers.ts`, `common.ts`) are forbidden for new feature code.
+- Hardcoded, non-parameterized configuration MUST be centralized in `src/config.ts` (for example, external service URLs).
+- `src/config.ts` MUST export a single default object named `config` and it MUST always be imported as `import config from ".../config.ts"`.
+- Non-trivial structured output (for example pages, documents, markdown, HTML, prompts, emails, or report bodies) MUST be stored in dedicated template files instead of being composed inline in source code.
+- Inline string building is allowed only for very small fragments where a template file would be disproportionate.
+- Template rendering strategy MAY be as simple or as capable as needed; choose the smallest approach that keeps the content outside application code.
+- Architecture decisions MUST default to the simplest structure that satisfies current requirements.
+- New files, modules, or layers MUST be introduced only when they solve present complexity, not anticipated future needs.
+- Simplicity is mandatory: if a design can be smaller, flatter, and more direct while staying correct, that simpler design MUST be chosen.
+- Speculative abstractions, placeholder extension points, and gratuitous indirection are forbidden.
+- Simplicity MUST NOT be interpreted as permission to remove valid architectural boundaries.
+- Distinct responsibilities that are already justified SHOULD remain separated.
+
+Good example:
+
+- `ai/examples/demo/src/config.ts`
+- `ai/examples/demo/src/invoice/invoice.service.ts`
+- `ai/examples/demo/src/invoice/invoice.errors.ts`
+- `ai/examples/demo/src/invoice/invoice.types.ts`
+- `ai/examples/demo/src/billing/billing.service.ts`
+
+Bad example:
+
+- `ai/examples/rules/class-first-bad.ts` (mixes concerns and does not keep feature boundaries)

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

@@ -0,0 +1,13 @@
+### 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:
+
+- `ai/examples/rules/async-good.ts`
+
+Bad example:
+
+- `ai/examples/rules/async-bad.ts`