schemantic 0.2.1 → 0.4.0

package/docs/superpowers/plans/2026-10-10-audit-remediation.md

@@ -0,0 +1,113 @@
+# Audit remediation implementation plan
+
+> **For agentic workers:** Use the systematic-debugging, test-driven-development and verification-before-completion skills. Independent plugin, CLI and schema work runs in parallel with explicitly bounded file ownership; integrate and review the complete generated contracts before completion.
+
+**Goal:** Correct all reproduced audit defects and remove or explicitly diagnose incomplete feature promises, then implement the agreed safe naming migration.
+
+**Architecture:** Keep the existing generator API, but centralize validated configuration, generated module/file assembly and schema naming/projections. Emit complete output in memory before an owned-file transaction; use schema metadata consistently for static types and runtime boundaries. Optional helpers remain explicit integrations unless a tested adapter is added.
+
+**Tech stack:** TypeScript, Node 20+, fetch, plain React hooks, optional Zod 4, Jest consumer/runtime tests.
+
+**Spec:** docs/REAUDIT.md and docs/NAMING_MIGRATION.md.
+
+## Constraints and decisions
+
+- Preserve previous authorized fixes and unrelated dirty workspace changes; do not reset, commit or publish.
+- All generated relative imports use `.js` specifiers, compatible with TS module resolution for Node ESM and bundlers; distinguish type imports from runtime enums.
+- Keep default output complete (types/client/index), React optional; public config allows omitted defaulted fields, internal config is validated/resolved.
+- Unsupported features receive explicit diagnostics or are removed from documentation; prospective expansion recommendations are not a promise to build every adapter/OAuth/UI feature.
+- CamelCase application properties must include schema-aware serialization/deserialization, with explicit preserve mode; never change static spelling alone.
+- The user has authorized execution of the existing audit roadmap. Continue implementation without another plan approval gate.
+
+## Review focus
+
+- Multiple tenants or colliding request URLs must not share cache results.
+- Case aliases, path ancestors and failed generation must not overwrite or partially replace existing output.
+- Media/status/schema selection must agree between generated return types and actual runtime values.
+- Async mutation completion, reset and unmount must not resurrect invalidated state.
+- Config/plugin combinations and naming collisions must fail clearly, never silently omit work.
+
+## Tasks
+
+### 1. Optional plugin contracts (parallel owner: fix_plugins)
+
+Files: src/plugins/request-deduplication.ts, branded-types.ts, zod-validation.ts, performance-monitoring.ts, builtin.ts, index.ts; new plugin-reaudit.test.ts.
+
+- [x] Reproduce R01/R06/R16/R17/R18 with assertions against freshly generated runtime/consumer modules.
+- [x] Fix canonical request identities/header scope, stale/invalidation/statistics/key callbacks.
+- [x] Emit branded shared declarations once and implement honest guards/feature switches.
+- [x] Correct Zod composition/constraints/permissive response behavior and ineffective exposed options.
+- [x] Synchronize monitoring exports/options; append requested reports as GeneratedFile records before commit; expose supported helper APIs.
+- [x] Run targeted Jest tests; integrate with full suite and re-audit plugin probes.
+
+### 2. CLI, guides and release gates (parallel owner: fix_cli_docs)
+
+Files: src/cli/index.ts, src/plugins/loader.ts, maintained guides, workflow YAML, publish scripts; new cli-reaudit.test.ts.
+
+- [x] Assert protected init, interactive failure status/defaults, config/discovery/validate parity, plugin load/generate resolution.
+- [x] Use shared resolveConfiguration(input): ResolvedSchemanticConfig; load plugins in the generation invocation.
+- [x] Implement meaningful supported flags or reject/remove ineffective ones; correct all public examples.
+- [x] Parse real npm pack sizes, add platform-sensitive CI and remove publishing scripts that mutate the working package name on failure.
+- [x] Run source-level tests, then freshly built spawned CLI tests and compile guide examples during integration.
+
+### 3. Schema/parser fidelity (parallel owner: fix_schema)
+
+Files: schema-type.ts/object-generator.ts/primitive-generator.ts, parser sources and schema types; new schema-reaudit.test.ts.
+
+Interface: schemaType sixth optional SchemaTypeOptions {direction?: 'request'|'response'; binary?: boolean; propertyName?: (wire: string) => string}, retaining fifth seen argument.
+
+- [x] Assert R13 dialect patches/boolean/components-only support and truthful YAML behavior.
+- [x] Fix heterogeneous dictionary modeling, allOf required-only and 3.1 reference sibling constraints.
+- [x] Add direction/binary/property-name options propagated through recursive schema generation.
+- [x] Compile valid and invalid consumer assignments; root integrates directional aliases/media handling.
+
+### 4. Core configuration and safe output (root)
+
+Files: src/core/configuration.ts, schemantic.ts, plugins/manager.ts, types/core.ts; new core-reaudit.test.ts.
+
+- [x] Assert R02/R14/R15/R21: case/ancestor collisions, validation refs, plugin hook failures, stale owned outputs, custom imports and ergonomic config.
+- [x] Separate optional input configuration from required resolved config; validate field types, supported flags and plugin entries.
+- [x] Build GeneratedFile records in memory; run after-generation hooks before commit; validate destinations; stage/backup/rollback owned output and manifest.
+- [x] Preserve arbitrary imports with type/value-aware module assembly; propagate plugin failures with names/hooks.
+- [x] Verify failed generation leaves existing output unchanged and removes only stale manifest-owned files after success.
+
+### 5. Client media/serialization/module contracts (root)
+
+Files: api-client-generator.ts, core assembly, generated endpoint types; new client-reaudit.test.ts.
+
+- [x] Assert R03/R05/R07–R12: auth casing, directional types, binary bytes, Path Item refs, schema-less/default/multiple/XML responses, object queries and strict/ESM compilers.
+- [x] Use case-insensitive header helpers, direction-aware request/response aliases, media-aware decoding/types and default response fallback.
+- [x] Serialize object queries by documented style/explode and diagnose unsupported encodings.
+- [x] Emit type-only/runtime imports correctly, qualify global binary helpers, emit only used helpers and `.js` specifiers.
+- [x] Run consumer compile and real local HTTP tests for outgoing bytes and incoming values.
+
+### 6. Hook lifecycle (root)
+
+Files: hook-generator.ts; new hook mutation tests alongside existing query tests.
+
+- [x] Assert reversed results/errors, overlapping loading, pending reset and unmount suppression.
+- [x] Implement latest-call state semantics and invalidation while retaining per-caller promise results.
+- [x] Verify query stability remains intact; mount actual React tests if dependencies available, otherwise retain explicit boundary.
+
+### 7. Naming migration (root, after core correctness)
+
+Files: naming/schema conversion modules, shared config, generators and plugin integration; new naming runtime/consumer tests.
+
+- [x] Assert both property modes, nested arrays/refs/dictionaries, optional/null, unions, collisions and immutable round trips.
+- [x] Emit application and wire mappings plus schema-aware converters; expose converters for types-only users.
+- [x] Connect request serialization/response deserialization and ensure validation/hooks follow the same names; preserve binary and enum values.
+- [x] Enable camelCase default only with verified wire round trips and document preserve-mode compatibility.
+
+### 8. Integration and completion
+
+- [x] Run full Jest, build/lint, all fixture modes, consumer matrix, audit probes and package inspection.
+- [x] Review the final changed contracts and audit-ID coverage with a fresh reviewer; correct material findings.
+- [x] Record exact closed/remaining items in docs/REMEDIATION.md; never claim full closure based only on fixture compilation.
+
+## Execution ledger
+
+- Started 2026-10-10. Previous baseline: 184 tests; defects recorded in the re-audit. Parallel owners instructed not to clean/rebuild shared dist. Root coordinates full builds and integration.
+
+- Integrated 2026-10-12: schema/client/plugin/CLI/hook fixes, camelCase HTTP boundaries, preservation mode, mounted React, independent review corrections. Fresh lockfile and scoped coverage-parser override audited clean. Final full and packaged-consumer gates in progress.
+
+- Completed 2026-10-12: full build/lint/coverage gate 316 tests in22 suites; 36 fixture combinations and five strict consumer configurations; zero npm audit advisories; archive inspection and isolated installed CommonJS/ESM/CLI/HTTP consumer passed. Windows sharing locks retry with path rechecks and bounded backoff. No commit or publication performed; deliberate support limits recorded in docs/REMEDIATION.md.

package/package.json

@@ -1,95 +1,114 @@
-{
-  "name": "schemantic",
-  "version": "0.2.1",
-  "description": "A fully typed, extensible TypeScript type generator for FastAPI OpenAPI schemas",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "bin": {
-    "schemantic": "dist/cli/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint -c eslint.config.mjs src/**/*.ts",
-    "lint:fix": "eslint -c eslint.config.mjs src/**/*.ts --fix",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "echo",
-    "publish:npm": "npm publish --access public",
-    "publish:gh": "npm pkg set name=@Cstannahill/schemantic && npm publish && npm pkg set name=schemantic",
-    "publish:both": "npm run publish:npm && npm run publish:gh"
-  },
-  "keywords": [
-    "typescript",
-    "openapi",
-    "fastapi",
-    "api-client",
-    "type-generation",
-    "api",
-    "codegen",
-    "client-generator",
-    "schema",
-    "rest-api",
-    "frontend",
-    "backend",
-    "full-stack",
-    "react",
-    "hooks",
-    "json-schema",
-    "developer-tools",
-    "automation"
-  ],
-  "author": "Christian Tannahill <ctan.dev@gmail.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Cstannahill/schemantic.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "homepage": "https://github.com/Cstannahill/schemantic#readme",
-  "bugs": {
-    "url": "https://github.com/Cstannahill/schemantic/issues"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.35.0",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^24.3.3",
-    "@typescript-eslint/eslint-plugin": "^8.43.0",
-    "@typescript-eslint/parser": "^8.43.0",
-    "eslint": "^9.35.0",
-    "jest": "^30.1.3",
-    "ts-jest": "^29.4.1",
-    "typescript": "^5.9.2",
-    "zod": "^4.1.12"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "files": [
-    "dist/**/*",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "docs/**/*",
-    "!dist/**/*.test.*",
-    "!dist/**/*.spec.*"
-  ],
-  "dependencies": {
-    "axios": "^1.12.1",
-    "chokidar": "^4.0.1",
-    "commander": "^14.0.1"
-  }
-}
+{
+  "name": "schemantic",
+  "version": "0.4.0",
+  "description": "A fully typed, extensible TypeScript type generator for FastAPI OpenAPI schemas",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "schemantic": "dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "pretest": "npm run build",
+    "prepack": "npm run build",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:release": "node scripts/run-release-tests.cjs",
+    "verify:fixtures": "node scripts/ci/verify-fixtures.cjs",
+    "verify:live": "node scripts/ci/verify-live.cjs",
+    "package:verify": "node scripts/ci/verify-package.cjs",
+    "release:prepare": "node scripts/release.cjs prepare",
+    "release:check": "node scripts/release.cjs check",
+    "release:notes": "node scripts/release.cjs notes",
+    "lint": "eslint -c eslint.config.mjs src/**/*.ts",
+    "lint:fix": "eslint -c eslint.config.mjs src/**/*.ts --fix",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "prepublishOnly": "npm run release:check && npm run lint && npm run test:release && npm test -- --runInBand",
+    "publish:npm": "npm run release:check && npm publish --access public"
+  },
+  "keywords": [
+    "typescript",
+    "openapi",
+    "fastapi",
+    "api-client",
+    "type-generation",
+    "api",
+    "codegen",
+    "client-generator",
+    "schema",
+    "rest-api",
+    "frontend",
+    "backend",
+    "full-stack",
+    "react",
+    "hooks",
+    "json-schema",
+    "developer-tools",
+    "automation"
+  ],
+  "author": "Christian Tannahill <ctan.dev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cstannahill/schemantic.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/Cstannahill/schemantic#readme",
+  "bugs": {
+    "url": "https://github.com/Cstannahill/schemantic/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-test-renderer": "^19.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "eslint": "^9.35.0",
+    "jest": "^30.1.3",
+    "js-yaml": "^4.3.2",
+    "react": "^19.3.0",
+    "react-test-renderer": "^19.3.0",
+    "semver": "^7.8.5",
+    "ts-jest": "^29.4.1",
+    "typescript": "^5.9.2",
+    "zod": "^4.1.12"
+  },
+  "overrides": {
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "^4.3.2"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/**/*",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*",
+    "!dist/__tests__/**"
+  ],
+  "dependencies": {
+    "axios": "^1.20.0",
+    "chokidar": "^4.0.1",
+    "commander": "^14.0.1"
+  }
+}

package/dist/__tests__/setup.d.ts

@@ -1,6 +0,0 @@
-/**
- * Jest setup file for global test configuration
- */
-declare const originalConsoleError: (message?: any, ...optionalParams: any[]) => void;
-declare const originalConsoleWarn: (message?: any, ...optionalParams: any[]) => void;
-//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,QAAA,MAAM,oBAAoB,mDAAgB,CAAC;AAC3C,QAAA,MAAM,mBAAmB,mDAAe,CAAC"}

package/dist/__tests__/setup.js

@@ -1,30 +0,0 @@
-"use strict";
-/**
- * Jest setup file for global test configuration
- */
-// Increase test timeout for integration tests
-jest.setTimeout(30000);
-// Mock console methods to reduce noise during tests
-const originalConsoleError = console.error;
-const originalConsoleWarn = console.warn;
-beforeEach(() => {
-    // Mock console.error and console.warn to suppress expected errors in tests
-    console.error = jest.fn();
-    console.warn = jest.fn();
-});
-afterEach(() => {
-    // Restore original console methods
-    console.error = originalConsoleError;
-    console.warn = originalConsoleWarn;
-    // Clear all mocks
-    jest.clearAllMocks();
-});
-// Set up environment variables for testing
-process.env.NODE_ENV = "test";
-// Dummy test to satisfy Jest requirement
-describe("Setup", () => {
-    it("should configure test environment", () => {
-        expect(process.env.NODE_ENV).toBe("test");
-    });
-});
-//# sourceMappingURL=setup.js.map

package/dist/__tests__/setup.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":";AAAA;;GAEG;AAEH,8CAA8C;AAC9C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAEvB,oDAAoD;AACpD,MAAM,oBAAoB,GAAG,OAAO,CAAC,KAAK,CAAC;AAC3C,MAAM,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;AAEzC,UAAU,CAAC,GAAG,EAAE;IACd,2EAA2E;IAC3E,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;IAC1B,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;AAC3B,CAAC,CAAC,CAAC;AAEH,SAAS,CAAC,GAAG,EAAE;IACb,mCAAmC;IACnC,OAAO,CAAC,KAAK,GAAG,oBAAoB,CAAC;IACrC,OAAO,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAEnC,kBAAkB;IAClB,IAAI,CAAC,aAAa,EAAE,CAAC;AACvB,CAAC,CAAC,CAAC;AAEH,2CAA2C;AAC3C,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC;AAE9B,yCAAyC;AACzC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE;IACrB,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/test-config.d.ts

@@ -1,36 +0,0 @@
-/**
- * Test configuration and utilities
- */
-import { SchemanticConfig } from "../types/core";
-import { OpenAPISchema } from "../types/openapi";
-/**
- * Create a test configuration
- */
-export declare function createTestConfig(overrides?: Partial<SchemanticConfig>): SchemanticConfig;
-/**
- * Create a minimal test schema
- */
-export declare function createTestSchema(): OpenAPISchema;
-/**
- * Create a complex test schema with various types
- */
-export declare function createComplexTestSchema(): OpenAPISchema;
-/**
- * Mock file system operations for tests
- */
-export declare const mockFs: {
-    mkdir: jest.Mock<any, any, any>;
-    writeFile: jest.Mock<any, any, any>;
-    readFile: jest.Mock<any, any, any>;
-    access: jest.Mock<any, any, any>;
-    readdir: jest.Mock<any, any, any>;
-};
-/**
- * Setup mock file system
- */
-export declare function setupMockFs(): void;
-/**
- * Reset mock file system
- */
-export declare function resetMockFs(): void;
-//# sourceMappingURL=test-config.d.ts.map

package/dist/__tests__/test-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test-config.d.ts","sourceRoot":"","sources":["../../src/__tests__/test-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAkB,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACxC,gBAAgB,CAiBlB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CA0QhD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,aAAa,CAoNvD;AAED;;GAEG;AACH,eAAO,MAAM,MAAM;;;;;;CAMlB,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAQlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}