human-to-code 0.1.4 → 0.1.6

package/docs/roadmap/java.md

@@ -0,0 +1,48 @@
+# Java support plan
+
+## Status today
+Level 1: `LANGUAGE_PROFILES` has `java` (`.java`), and `.java` is scanned for
+inline `// @human` markers. No grounded profile.
+
+## Target profile
+- `Ecosystem`: `java`.
+- Variants: `maven` (`pom.xml`) and `gradle` (`build.gradle`/`.kts`,
+  `settings.gradle`), with Spring Boot recorded as a framework signal first
+  and promoted to its own variant once the adapter proves reliable.
+- Versions: JDK 17+ (from `maven.compiler.release` / Gradle toolchain block).
+
+## Detection signals (static only)
+- `pom.xml` parent/modules for Maven multi-module ownership.
+- `settings.gradle(.kts)` `include(...)` for Gradle subprojects — parsed
+  textually and conservatively; unresolvable dynamic includes → `NEEDS_INPUT`.
+- `src/main/java`, `src/test/java` for source/test roots; `@SpringBootApplication`
+  as an entry-point signal. Never execute Maven/Gradle.
+
+## Version evidence
+Maven: exact `<version>` pins in `pom.xml` (property-indirected versions
+resolved only when the property is a literal in the same reactor).
+Gradle: version catalogs (`gradle/libs.versions.toml`) and lockfiles
+(`gradle.lockfile`) when present; otherwise the dependency is unproven and
+API grounding for it must refuse.
+
+## Validation plan
+- Maven: `["mvn", "-B", "-q", "verify"]`. Gradle: `["./gradlew", "--no-daemon", "build"]`
+  only when the wrapper exists (wrapper jars are arbitrary code — sandbox only).
+- JDK image recorded by version; mismatch is `INCONCLUSIVE`.
+
+## Skill pack
+Package/directory correspondence; constructor injection over field injection
+(Spring); JUnit 5 conventions; no reflection-based config edits; generated
+sources under `target/`/`build/` are protected.
+
+## Risks & gates
+Annotation processors, Gradle build-script edits, `module-info.java`
+changes, and dependency additions are elevated-risk; build scripts are
+executable code and must never be model-editable.
+
+## Checklist
+1. `Ecosystem` union + `analysis/adapters/java.ts`.
+2. `java/maven`, `java/gradle` at `preview` in `support-matrix.ts`.
+3. Register adapter; Java/Spring skill pack.
+4. Adversarial tests: multi-module reactors, dynamic Gradle includes, version properties, wrapper absence, stable fingerprints.
+5. Docs updates (MODULES.md, README support matrix).

package/docs/roadmap/kotlin.md

@@ -0,0 +1,44 @@
+# Kotlin support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`; `.kt` not scanned for markers.
+
+## Target profile
+- `Ecosystem`: `kotlin` (JVM/Gradle first; Android later as its own variant
+  because of SDK/emulator validation constraints).
+- Variants: `gradle-jvm`, then `android` (deferred until a headless
+  validation story exists — unit tests only, no instrumented tests).
+- Versions: Kotlin ≥ 1.9 (from the Kotlin Gradle plugin version in the
+  version catalog or build script literals).
+
+## Detection signals (static only)
+- `build.gradle.kts` with `kotlin("jvm")`/`org.jetbrains.kotlin` plugin
+  (textual, conservative), `gradle/libs.versions.toml`,
+  `src/main/kotlin`, `src/test/kotlin`; `AndroidManifest.xml` marks the
+  android variant. Never execute Gradle.
+
+## Version evidence
+Version catalogs and `gradle.lockfile` when present; literal plugin/dependency
+versions otherwise. Dynamic version expressions leave deps unproven.
+
+## Validation plan
+- `["./gradlew", "--no-daemon", "test"]` (wrapper = arbitrary code, sandbox
+  only, deps preinstalled/cached offline). Android: `testDebugUnitTest` only.
+
+## Skill pack
+Null-safety idioms, data classes, coroutines conventions (structured
+concurrency, no `GlobalScope`), JUnit5/Kotest layout, `build/` and generated
+KSP/KAPT output protected.
+
+## Risks & gates
+KSP/KAPT processors, Gradle script edits, multiplatform targets, and JNI are
+elevated-risk. Shares most gates with the Java plan — build one Gradle
+inventory helper both adapters reuse (`analyzer-utils.ts` addition).
+
+## Checklist
+0. Add `kotlin` to `LANGUAGE_PROFILES` (`.kt`) and scan `.kt`/`.kts` for `// @human`.
+1. `Ecosystem` union + `analysis/adapters/kotlin.ts` (shared Gradle helpers with java.md's adapter).
+2. `kotlin/gradle-jvm` at `preview`; `kotlin/android` deferred and documented.
+3. Register adapter; Kotlin skill pack.
+4. Tests: catalog vs literal versions, multiplatform refusal, Android detection, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/php.md

@@ -0,0 +1,42 @@
+# PHP support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES` (direct path would fall back to a
+`.txt` profile) and `.php` is not scanned for markers.
+
+## Target profile
+- `Ecosystem`: `php`.
+- Variants: `composer-app`, `laravel` (artisan + `bootstrap/app.php`),
+  `symfony` later.
+- Versions: PHP ≥ 8.2 (from `composer.json` `require.php`).
+
+## Detection signals (static only)
+- `composer.json` (`require`, `autoload.psr-4`), `composer.lock`,
+  `artisan`, `routes/`, `app/Http/` for Laravel; `phpunit.xml(.dist)` for
+  tests. Never run composer or artisan.
+
+## Version evidence
+`composer.lock` `packages[].version` is exact; `composer.json` ranges alone
+leave dependencies unproven.
+
+## Validation plan
+- `["vendor/bin/phpunit"]`; `["vendor/bin/phpstan", "analyse"]` when
+  configured; `["php", "-l", "<changed files>"]` as a cheap syntax gate.
+  `vendor/` must be preinstalled in the image (no network).
+
+## Skill pack
+PSR-4 path↔namespace correspondence, PSR-12 style, Laravel conventions
+(form requests for validation, Eloquent scopes), `vendor/` and framework
+cache dirs protected.
+
+## Risks & gates
+Laravel migrations review-only; `eval`/dynamic includes opaque to import
+grounding; service-provider registration changes are elevated-risk.
+
+## Checklist
+0. Add `php` to `LANGUAGE_PROFILES` (`.php`) and `.php` to `SCANNED_EXTENSIONS` — direct-path quick win.
+1. `Ecosystem` union + `analysis/adapters/php.ts`.
+2. `php/composer-app`, `php/laravel` at `preview`.
+3. Register adapter; PHP/Laravel skill pack.
+4. Tests: missing lockfile, PSR-4 mismatches, Laravel vs plain-composer ambiguity, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/ruby.md

@@ -0,0 +1,46 @@
+# Ruby support plan
+
+## Status today
+Level 1: `LANGUAGE_PROFILES` has `ruby` (`.rb`); `.rb` is **not** yet in
+`SCANNED_EXTENSIONS`, so inline `# @human` markers in Ruby files are not
+discovered — adding it is a one-line prerequisite worth shipping early.
+
+## Target profile
+- `Ecosystem`: `ruby`.
+- Variants: `gem` (gemspec), `rails` (config/application.rb + bin/rails),
+  `rack` (config.ru without Rails).
+- Versions: Ruby ≥ 3.1 (from `.ruby-version` / Gemfile `ruby` directive).
+
+## Detection signals (static only)
+- `Gemfile` + `Gemfile.lock`; `*.gemspec`; `config/application.rb`,
+  `config/routes.rb`, `app/{models,controllers}` for Rails layout;
+  `spec/` (RSpec) vs `test/` (Minitest) for test roots. Never run `bundle`.
+
+## Version evidence
+`Gemfile.lock` `GEM/specs` entries are exact — this is the grounding source;
+a Gemfile without a lockfile leaves dependencies unproven.
+
+## Validation plan
+- `["bundle", "exec", "rspec"]` or `["bundle", "exec", "rails", "test"]`
+  depending on detected harness; `["bundle", "exec", "rubocop"]` when
+  `.rubocop.yml` exists. Gems must be vendored/preinstalled in the image —
+  no network in the sandbox.
+
+## Skill pack
+Rails conventions (strong parameters, concerns, service objects), RSpec
+structure, frozen-string-literal pragma, Zeitwerk autoloading constraints
+(file path ↔ constant name), `db/schema.rb` and migrations protected.
+
+## Risks & gates
+Rails migrations (review-only, never applied), monkey-patching core classes,
+`method_missing` metaprogramming, and native-extension gems are
+elevated-risk. Dynamic requires make import grounding partially opaque —
+document as an accepted limitation like Python's.
+
+## Checklist
+0. Add `.rb` to `SCANNED_EXTENSIONS` in `pipeline/simple.ts` (independent quick win).
+1. `Ecosystem` union + `analysis/adapters/ruby.ts`.
+2. `ruby/gem`, `ruby/rails`, `ruby/rack` at `preview`.
+3. Register adapter; Ruby/Rails skill pack.
+4. Tests: lockfile absence, Rails vs Rack ambiguity, engine subdirectories, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/sql.md

@@ -0,0 +1,48 @@
+# SQL support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`. SQL also intersects an existing
+invariant: database migrations may be *generated for review* but are never
+applied — any SQL profile inherits that rule wholesale.
+
+## Target profile
+- `Ecosystem`: `sql`.
+- Variant: `migration-set` — a directory of ordered migration files managed
+  by a recognizable tool (Flyway `V__*.sql`, dbmate, golang-migrate,
+  Prisma/TypeORM/Alembic SQL output). Free-floating `.sql` files stay on the
+  general fallback.
+- Dialects recorded as signals (postgres/mysql/sqlite) from tool config, not
+  guessed from syntax.
+
+## Detection signals (static only)
+- Migration tool config (`flyway.conf`, `dbmate` env refs, `migrations/`
+  naming schemes), ordered filename conventions, and the owning framework's
+  adapter (a NestJS/FastAPI workspace may own its migrations directory).
+
+## Version evidence
+The "dependency" is the schema itself: prior migrations in order are the
+grounding evidence a new migration builds on. No package versions.
+
+## Validation plan
+- Syntax-only gates in the sandbox: `["sqlfluff", "lint", "--dialect", "<dialect>"]`
+  or the tool's dry-run/check mode where one exists **without a database**.
+- Optional stronger tier later: apply to a disposable in-container database
+  (sqlite/postgres in the image) — still never the operator's database.
+
+## Skill pack
+One reversible change per migration (paired down-migration when the tool
+supports it), no destructive `DROP` without explicit contract authorization,
+idempotence patterns, naming convention of the detected tool.
+
+## Risks & gates
+Everything: destructive statements, data backfills, and permission changes
+are elevated-risk requiring explicit authorization in the contract. Applied
+migration files are immutable history — protected paths; only new files may
+be created.
+
+## Checklist
+1. `Ecosystem` union + `analysis/adapters/sql.ts` keyed on migration-tool detection.
+2. `sql/migration-set` at `preview`.
+3. SQL skill pack; extend patch policy tests for "create-only in migrations dir".
+4. Tests: ordering, tool detection, destructive-statement gating, dialect signals.
+5. Docs updates.

package/docs/roadmap/swift.md

@@ -0,0 +1,43 @@
+# Swift support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`; `.swift` not scanned for markers.
+
+## Target profile
+- `Ecosystem`: `swift`.
+- Variants: `spm-package` (Package.swift) first. Xcode-project apps
+  (`.xcodeproj`/`.xcworkspace`) are explicitly **out of scope** initially —
+  pbxproj is too dynamic to analyze honestly; declare `UNSUPPORTED`.
+- Versions: Swift ≥ 5.9 (from `// swift-tools-version:` header).
+
+## Detection signals (static only)
+- `Package.swift` tools-version comment line (parsed textually — the
+  manifest itself is Swift code and must never be evaluated), `Package.resolved`,
+  `Sources/`, `Tests/` layout.
+
+## Version evidence
+`Package.resolved` pins exact dependency versions; targets/products read
+only from conservative literal parsing of `Package.swift`, refusing
+computed manifests with `NEEDS_INPUT`.
+
+## Validation plan
+- `["swift", "build"]`, `["swift", "test"]` in a Swift toolchain image
+  (Linux). Apple-platform-only packages (UIKit imports) are `INCONCLUSIVE`
+  on a Linux sandbox — say so rather than skipping silently.
+
+## Skill pack
+Target/directory correspondence, XCTest conventions, access-control
+(`public`/`internal`) discipline for library targets, `Package.resolved`
+protected.
+
+## Risks & gates
+Manifest edits (executable code), macros/plugins (arbitrary build-time
+code), and `@objc`/C interop are elevated-risk.
+
+## Checklist
+0. Add `swift` to `LANGUAGE_PROFILES` (`.swift`) and scan `.swift` for `// @human`.
+1. `Ecosystem` union + `analysis/adapters/swift.ts`.
+2. `swift/spm-package` at `preview`; Xcode variants declared unsupported.
+3. Register adapter; Swift skill pack.
+4. Tests: computed manifests refused, platform-gated packages, resolved-file absence, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/terraform.md

@@ -0,0 +1,47 @@
+# Terraform / HCL support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`; `.tf` not scanned for markers
+(`# @human` comment form would parse; extension isn't scanned).
+
+## Target profile
+- `Ecosystem`: `terraform`.
+- Variants: `root-module` (has backend/provider config) and `child-module`
+  (reusable module without backend). Workspaces with multiple root modules
+  need explicit targeting → `NEEDS_INPUT`, mirroring the multi-app rule.
+- Versions: `required_version` and `required_providers` blocks.
+
+## Detection signals (static only)
+- `*.tf`/`*.tf.json`, `.terraform.lock.hcl`, `terraform.tfvars`,
+  `backend`/`provider` blocks (textual HCL parsing, conservative),
+  `modules/` layout.
+
+## Version evidence
+`.terraform.lock.hcl` pins exact provider versions with hashes — first-class
+grounding evidence. Module registry sources with versions count; git-ref
+module sources without a pinned rev are unproven.
+
+## Validation plan
+- `["terraform", "fmt", "-check"]` and `["terraform", "validate"]` with a
+  pre-initialized `.terraform` directory baked into the image/fixture
+  (validation has no network for `init`). `plan`/`apply` are out of scope:
+  plan needs credentials and state — never available in the sandbox.
+
+## Skill pack
+Variable/output descriptions and types, no inline credentials (secret
+scanner already blocks values; the pack forbids the pattern), tagging
+conventions, `for_each` over `count` for stable addresses, state-affecting
+rename awareness (`moved` blocks).
+
+## Risks & gates
+Everything that changes resource addresses (renames without `moved`),
+`destroy`-provoking changes, provider version bumps, and backend changes
+are elevated-risk. The tool must be explicit that `validate`-clean ≠
+apply-safe — plan/apply stay human-owned.
+
+## Checklist
+0. Scan `.tf` for `# @human` markers (direct-path quick win, `LANGUAGE_PROFILES` entry `hcl`/`.tf`).
+1. `Ecosystem` union + `analysis/adapters/terraform.ts`.
+2. `terraform/root-module`, `terraform/child-module` at `preview`.
+3. Skill pack; tests for lockfile evidence, multi-root refusal, moved-block gating.
+4. Docs updates (including the honest validate-vs-apply distinction in README).

package/docs/roadmap/yaml.md

@@ -0,0 +1,47 @@
+# YAML config support plan
+
+## Status today
+Level 2 only. YAML is not a programming language here — the meaningful
+target is *schema-validated configuration editing* (CI workflows, K8s
+manifests, app config), where correctness is checkable without execution.
+
+## Target profile
+- `Ecosystem`: `yaml-config`.
+- Variants by proven schema family: `github-actions`
+  (`.github/workflows/*.yml`), `kubernetes` (apiVersion/kind docs),
+  `generic` (only when a JSON Schema is discoverable via
+  `# yaml-language-server: $schema=` or operator config).
+- Unschema'd YAML stays on the general fallback — there is nothing to
+  validate, so nothing to profile.
+
+## Detection signals (static only)
+- Path conventions (`.github/workflows/`), `apiVersion`/`kind` keys,
+  explicit `$schema` pragmas, `kustomization.yaml`.
+
+## Version evidence
+The schema is the "dependency": pin the schema source (bundled
+GitHub-Actions/K8s schemas shipped as immutable package data, like compiler
+skills) and record which schema+version validated the patch.
+
+## Validation plan
+- Offline schema validation in-process or via a bundled validator; K8s:
+  `["kubeconform", "-strict", "<files>"]` with schemas preloaded in the
+  image. Never `kubectl apply`.
+
+## Skill pack
+Anchors/aliases used sparingly, no duplicate keys, quoting rules for
+booleans/versions (Norway problem), GitHub Actions pinning conventions
+(action SHAs), K8s resource limits present.
+
+## Risks & gates
+CI workflow edits are supply-chain-sensitive: adding `run:` steps, changing
+action refs, or touching secrets contexts is elevated-risk and needs
+explicit contract authorization. Secrets scanning already covers values;
+the skill pack must also forbid *referencing* new secret names silently.
+
+## Checklist
+1. `Ecosystem` union + `analysis/adapters/yaml-config.ts`.
+2. Variants at `preview`; bundle schema data as frozen package assets.
+3. Skill pack; patch-policy tests for workflow-edit gating.
+4. Tests: schema discovery, multi-doc files, duplicate keys, unschema'd refusal.
+5. Docs updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-to-code",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Safely turn reviewed natural-language change contracts into validated code patches.",
   "type": "module",
   "main": "./dist/index.js",