app-modernization-inception

name

app-modernization-inception

description

INCEPTION phase (assessment) of the optional application-modernization module: scan an application and classify every site impacted by a database migration — embedded SQL, datasource/ORM configuration, entity mappings, stored-routine call sites, error-code handling and result-set typing. Engine-agnostic; reads the active pair's rules from engines/<pair>/app/. Invoked by app-modernization-orchestrator, which turns this assessment into the gated change plan; read-only, edits nothing. Produces migrations/<project>/05-application/01-assessment/inventory.md.

Application Modernization — Inception (assessment)

Find everything the migration affects, classify it, and be honest about what cannot be resolved statically. This skill reads and reports only — it never edits.

Inputs: 00-intake/app-intake.md (stack, scope), 01-assessment/app-contract.md (what the migration changed), engines/<pair>/app/app-config.yaml and app-sql-rules.md.

Scope discipline

Search only the in-scope source directories. Always exclude build output and dependencies: target/, build/, bin/, obj/, dist/, out/, node_modules/, .git/, vendor/, __pycache__/, *.class, *.jar, *.dll, minified assets.

A hit inside build output means the artifact is stale, not that there is a site to convert. Report such files separately as stale build artifacts, and note any .bak/.orig leftovers from previous ad-hoc conversions — they are not conversion targets.

Categories to inventory

A. Connectivity & framework configuration

Datasource URL, driver class, ORM dialect, connection pool, schema/search-path selection. Typical locations: application.properties|yml, appsettings*.json, web.config, persistence.xml, hibernate.cfg.xml, *.env, Helm/Terraform values, Dockerfiles, CI config. Record the file, the key, and the current value — redact passwords (password=***).

Also scan CODE that parses or builds connection URLs — grep for jdbc:, the driver class name, and URL-string surgery (split, substring, regex) on a datasource URL. In two real runs this was missed by config-only scanning: display/diagnostic classes split the URL on Oracle's @// token, and their fallback echoed the raw URL — a credential-leak path once query parameters carry secrets. URL format assumptions are code sites, not config sites.

B. Embedded SQL

Classify each site by tier, because tier determines whether it can be converted safely:

Tier	What	Conversion approach
1	Externalised SQL (*.sql, MyBatis/iBatis mappers, .xml)	convert directly
2	Complete statement in a constant, annotation or literal (@Query, const string)	convert directly
3	Assembled at runtime (StringBuilder, conditional fragments, dynamic WHERE)	reconstruct the full statement first, then convert; never rewrite a fragment in isolation
4	Generated by a builder/ORM criteria API, or fetched from the DB/config	usually no SQL text to edit — fix the generator, the dialect, or flag for redesign

For each site record: file, line range, tier, whether the statement is complete, the constructs found, and mechanical vs behavioural.

Search terms come from the pair's app-sql-rules.md. For an Oracle source, at minimum: SYSDATE, SYSTIMESTAMP, NVL, NVL2, DECODE, DUAL, ROWNUM, CONNECT BY, (+), MINUS, LISTAGG, TO_DATE, TO_CHAR, TRUNC, ADD_MONTHS, MONTHS_BETWEEN, NEXTVAL, CONTAINS(, CATSEARCH, SCORE(, /*+, FETCH FIRST, REGEXP_. For SQL Server: GETDATE, ISNULL, TOP , IDENTITY, @@IDENTITY, SCOPE_IDENTITY, LEN(, MERGE, CROSS APPLY, OUTER APPLY, NOLOCK, + string concat, DATEADD, DATEDIFF, CONVERT(.

C. ORM entity mappings

Per stack, the same class of site:

• JPA/Hibernate: @Table/@Column/@Entity names — especially quoted identifiers, which pin the old case; @SequenceGenerator/@GeneratedValue strategies, type converters, @Lob, @Enumerated, ddl-auto/schema-generation settings.
• EF Core: ToTable/HasColumnName/DbSet naming conventions, OnModelCreating configuration, value converters, HasDefaultValueSql (dialect-specific SQL inside the model!), owned types, and any Database.EnsureCreated/migration invocation at startup.
• MyBatis/Dapper/SQLAlchemy/Sequelize: mapping files or attribute conventions equivalent to the above.

Cross-check mapped names against the SOURCE catalog. For each explicit table mapping (JPA @Table(name=…), EF ToTable("…")/DbSet conventions), confirm the named table actually exists in the source schema. Real apps drift: one mapped Order → ToTable("Orders") while the source table was Order — the migration surfaces such drift as a hard failure, so classify it at inventory time (conform to the migrated name + flag), not during build fixing.

For EF Core apps specifically, record that the model emits quoted PascalCase identifiers: a pure-LINQ app with zero SQL text still breaks against a case-folded schema, so the change plan must include the OnModelCreating lower-case fold (see the pair's app-sql-rules).

D. Stored-routine call sites

CallableStatement, { call … }, @Procedure, EntityManager.createStoredProcedureQuery, Dapper CommandType.StoredProcedure, EXEC. For each: the routine name as called, whether the migration renamed it (package flattening), whether it became a function rather than a procedure, OUT/ref-cursor parameters, and whether the routine lost an internal COMMIT (making the caller responsible for the transaction).

E. Error handling

getErrorCode(), ORA- string matching, SQLException subclasses, @SQLExceptionTranslator, .NET OracleException.Number, SQL Server SqlException.Number. Each must move to the target's error identity (SQLSTATE for PostgreSQL, error numbers for MySQL) using the mapping recorded in the migration's conversion log.

F. Result-set typing & column access

Same class of site per stack:

• JDBC: rs.getInt("…") on a COUNT(*) (now bigint → getLong), column lookups by the source engine's case, getObject casts, getDate vs getTimestamp.
• ADO.NET/Dapper: reader["Col"] / reader.GetInt32(...) on counts (→ GetInt64), ordinal-vs-name access, DataTable typing, Dapper materialization of changed types (bit→boolean binds true/false, not 0/1).
• All stacks: boolean-vs-numeric flag reads and date/time precision reads.

G. Schema-qualified references in app code

Hard-coded SCHEMA.TABLE prefixes, and any search_path/default-schema assumption.

H. Build dependencies

The source database driver (and any Oracle/SQL-Server-only library) in pom.xml, *.csproj, requirements.txt, package.json. Note whether the target driver is already present — a half-finished earlier attempt is common.

Output — 01-assessment/inventory.md

1. Summary table: category → site count → files touched → mechanical / behavioural / blocked.
2. Per-category detail, each site with file, line, tier, current code and the construct found.
3. Behavioural list — sites that can change results silently, called out separately.
4. Blocked / undecidable — Tier 3/4 statements that cannot be reconstructed statically, routines whose target shape is unknown, dynamic SQL from config or the database.
5. Not-a-target — stale build artifacts, .bak leftovers, vendored code.
6. Coverage caveat, stated plainly: static scanning cannot find SQL assembled from configuration, generated at runtime, or stored in the database. If the app has integration tests or a query log, say so — running them is the reliable way to surface the remainder.

Do not propose fixes here; that is the change plan's job. Inventory establishes what exists.