access-fieldkit 0.1.0__py3-none-any.whl

access_fieldkit/__init__.py

@@ -0,0 +1,2 @@
+"""Read-only extraction and landing tools for Microsoft Access databases."""
+__version__ = "0.1.0"

access_fieldkit/__main__.py

@@ -0,0 +1,69 @@
+"""Command-line entry point; read-only Access handling by default."""
+import argparse
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from .assessment import assess, markdown
+from .landing import load, reconcile, read_manifest
+from .runtime import run_reader
+from .tool_probe import probe
+
+
+def main(argv=None):
+    parser=argparse.ArgumentParser(prog='access-fieldkit',description='Inspect and stage Access databases without silently losing legacy data')
+    parser.add_argument('--jackcess-jar',help='Use a local Jackcess 5.0.4 jar; useful for offline work')
+    cmd=parser.add_subparsers(dest='command',required=True)
+    for action in ('inspect','export'):
+        p=cmd.add_parser(action, help=f'{action.title()} a source Access file (never writes to source)')
+        p.add_argument('source',type=Path)
+        p.add_argument('--out',type=Path,required=True)
+    p=cmd.add_parser('assess',help='Write a migration assessment based on exported native metadata')
+    p.add_argument('folder',type=Path);p.add_argument('--out',type=Path)
+    p=cmd.add_parser('load-sqlite',help='Load raw data into a loss-aware SQLite landing database')
+    p.add_argument('folder',type=Path);p.add_argument('target',type=Path);p.add_argument('--force',action='store_true')
+    p=cmd.add_parser('reconcile',help='Compare every exported Access value against the landing database')
+    p.add_argument('folder',type=Path);p.add_argument('target',type=Path)
+    p=cmd.add_parser('probe-tools',help='Compare the native inventory with any installed alternative readers')
+    p.add_argument('source',type=Path);p.add_argument('folder',type=Path);p.add_argument('--out',type=Path)
+    args=parser.parse_args(argv)
+    try:
+        if args.command in ('inspect','export'):
+            if args.out.exists():
+                raise FileExistsError('Output folder already exists; choose a new directory')
+            args.out.parent.mkdir(parents=True,exist_ok=True)
+            folder=Path(tempfile.mkdtemp(prefix='.access-fieldkit-',dir=args.out.parent))
+            try:
+                run_reader(args.command,args.source,folder,args.jackcess_jar)
+                folder.rename(args.out)
+            finally:
+                if folder.exists():shutil.rmtree(folder)
+            print('Manifest:',args.out/'manifest.json')
+        elif args.command=='assess':
+            result=assess(args.folder)
+            md=markdown(result)
+            if args.out:
+                args.out.parent.mkdir(parents=True,exist_ok=True)
+                args.out.write_text(md,encoding='utf-8')
+            else:print(md)
+            print(json.dumps({'findings':len(result['findings']),'tables':result['tables'],'rows':result['rows']}))
+        elif args.command=='probe-tools':
+            result=probe(args.source,args.folder)
+            output=json.dumps(result,indent=2)
+            if args.out:
+                args.out.parent.mkdir(parents=True,exist_ok=True)
+                args.out.write_text(output+'\n',encoding='utf-8')
+            print(output)
+        elif args.command=='load-sqlite':
+            print(json.dumps(load(args.folder,args.target,args.force),indent=2))
+        elif args.command=='reconcile':
+            result=reconcile(args.folder,args.target)
+            print(json.dumps(result,indent=2))
+            if not result['valid']: return 2
+        return 0
+    except Exception as exc:
+        print(f'{args.command}: {exc}',file=sys.stderr)
+        return 1
+
+if __name__=='__main__':raise SystemExit(main())

access_fieldkit/assessment.py

@@ -0,0 +1,71 @@
+"""Object-level migration inventory from extracted native Access metadata."""
+import json
+import re
+from pathlib import Path
+from .landing import read_manifest, iter_rows
+
+DANGER_SQL = [
+    ('ui_parameter',r'\bForms\s*!|\bReports\s*!','Form/report-bound reference; replace with explicit API parameter'),
+    ('domain_aggregate',r'\b(?:DLookup|DSum|DCount|DAvg|DMax|DMin)\s*\(','Jet domain aggregate; rewrite as SQL join/subquery'),
+    ('vba_expression',r'\b(?:Nz|IIf|Format|DateDiff|CDate)\s*\(','Access expression; check null, date and rounding semantics'),
+    ('crosstab',r'\bTRANSFORM\b','Crosstab/pivot requires a target-specific query'),
+    ('parameters',r'\bPARAMETERS\b','Parameter declaration; adapt to the target driver'),
+    ('action_query',r'^\s*(?:UPDATE|DELETE|INSERT|SELECT.+INTO)\b','Review the write side effects before conversion'),
+    ('wildcard',r"\bLIKE\s+['\"]\*",'Access wildcard differs from SQL LIKE'),
+]
+
+
+def assess(folder):
+    folder = Path(folder)
+    source = read_manifest(folder,require_export=False)
+    findings=[]
+    def add(level,code,location,detail):
+        findings.append({'level':level,'code':code,'location':location,'detail':detail})
+    for table in source['tables']:
+        name=table['name']; cols=table['columns']; indexes=table['indexes']
+        if not any(i['primary'] for i in indexes):
+            add('high','missing_primary_key',name,'Keyless tables can have duplicate rows and ambiguous linked-table updates')
+        for col in cols:
+            t=col['type']; location=f'{name}.{col["name"]}'
+            if t in ('COMPLEX_TYPE','OLE'):
+                add('high','complex_or_binary_column',location,'Handle attachments/OLE explicitly, and check actual bytes')
+            if t in ('MONEY','NUMERIC'):
+                add('medium','exact_decimal',location,'Preserve decimal scale and define an approved rounding policy')
+            if t == 'SHORT_DATE_TIME':
+                add('info','date_range',location,'Check pre-1753 dates and timestamp precision before SQL Server datetime conversion')
+            if col['name'].casefold() in {'order','select','from','user','table','group','where'}:
+                add('medium','reserved_identifier',location,'Quote target identifiers or use an explicit mapping')
+        if source['exported']:
+            dates=[i for i,c in enumerate(cols) if c['type']=='SHORT_DATE_TIME']
+            if dates:
+                older=0
+                for _,row in iter_rows(folder,table):
+                    for i in dates:
+                        if isinstance(row[i],str) and re.match(r'^(?:0\d\d\d|1[0-6]\d\d|17[0-4]\d|175[0-2])-\d\d-\d\d',row[i]):
+                            older+=1
+                if older:
+                    add('high','pre_1753_dates',name,f'{older} dates predate SQL Server datetime minimum; use date/datetime2')
+    for query in source['queries']:
+        sql=query.get('sql')
+        if not sql:
+            add('high','unreadable_query',query['name'],'Query SQL could not be reconstructed; examine in Windows Access')
+            continue
+        for code,pattern,message in DANGER_SQL:
+            if re.search(pattern,sql,re.I|re.S):
+                add('medium',code,query['name'],message)
+    for warning in source.get('warnings',[]):
+        add('medium','extractor_warning','database',warning)
+    add('high','uninspected_application_objects','Access frontend','Forms, reports, macros and VBA require Windows Access inventory; Java/Jet table inspection does not certify them')
+    return {'source_file_sha256':source['file_sha256'], 'tables':len(source['tables']),
+            'rows':source['total_rows'],'saved_queries':len(source['queries']),
+            'findings':findings,'scope':'database objects; no Access UI/VBA execution'}
+
+
+def markdown(report):
+    lines=['# Access migration assessment', '',f"Tables: {report['tables']} · Rows: {report['rows']} · Saved queries: {report['saved_queries']}",
+           '', 'This inventory is based on native database metadata. Access forms, reports, macros and VBA still need a Windows application audit.',
+           '', '| Severity | Object | Issue | Next action |', '|---|---|---|---|']
+    for f in report['findings']:
+        def clean(s):return str(s).replace('|','\\|').replace('\n',' ')
+        lines.append(f"| {clean(f['level'])} | `{clean(f['location'])}` | {clean(f['code'])} | {clean(f['detail'])} |")
+    return '\n'.join(lines)+'\n'

access_fieldkit/java/AccessReader.java

@@ -0,0 +1,120 @@
+import com.healthmarketscience.jackcess.*;
+import com.healthmarketscience.jackcess.query.Query;
+import java.io.*;
+import java.math.*;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.*;
+import java.security.MessageDigest;
+import java.time.*;
+import java.util.*;
+
+/** Read-only ACE/Jet inventory and loss-aware row extraction. No Access runtime emulation. */
+public final class AccessReader {
+  private static String j(String s) {
+    StringBuilder b = new StringBuilder("\"");
+    for (int i=0; i<s.length(); i++) {
+      char c=s.charAt(i);
+      switch(c) {
+        case '\"': b.append("\\\""); break;
+        case '\\': b.append("\\\\"); break;
+        case '\n': b.append("\\n"); break;
+        case '\r': b.append("\\r"); break;
+        case '\t': b.append("\\t"); break;
+        default:
+          if (c<32 || (Character.isHighSurrogate(c) && (i+1 == s.length() || !Character.isLowSurrogate(s.charAt(i+1)))) || Character.isLowSurrogate(c) && (i == 0 || !Character.isHighSurrogate(s.charAt(i-1)))) {
+            b.append(String.format("\\u%04x",(int)c));
+          } else b.append(c);
+      }
+    }
+    return b.append('\"').toString();
+  }
+  private static String val(Object v) {
+    if(v==null) return "null";
+    if(v instanceof byte[]) return "{\"$binary\":" + j(Base64.getEncoder().encodeToString((byte[])v)) + "}";
+    if(v instanceof Boolean) return v.toString();
+    if(v instanceof BigDecimal) return "{\"$decimal\":" + j(((BigDecimal)v).toPlainString()) + "}";
+    if(v instanceof Number) {
+      if(v instanceof Double || v instanceof Float) {
+        if(!Double.isFinite(((Number)v).doubleValue())) throw new IllegalStateException("Non-finite floating point data");
+        return "{\"$float\":" + j(v.toString()) + "}";
+      }
+      return v.toString();
+    }
+    if(v instanceof LocalDateTime || v instanceof LocalDate || v instanceof LocalTime || v instanceof OffsetDateTime) return j(v.toString());
+    if(v instanceof java.util.Date) return j(((java.util.Date)v).toInstant().atZone(ZoneOffset.UTC).toLocalDateTime().toString());
+    if(v instanceof CharSequence || v instanceof Character) return j(v.toString());
+    throw new IllegalArgumentException("Unsupported Access value type " + v.getClass().getName() + "; no silent string coercion");
+  }
+  private static String array(List<String> parts) { return "[" + String.join(",",parts) + "]"; }
+  private static String sha(Path p) throws Exception {
+    MessageDigest md=MessageDigest.getInstance("SHA-256");
+    try(InputStream in=Files.newInputStream(p)) { byte[] block=new byte[65536]; int n; while((n=in.read(block))!=-1) md.update(block,0,n); }
+    StringBuilder s=new StringBuilder(); for(byte b: md.digest()) s.append(String.format("%02x",b & 255)); return s.toString();
+  }
+  private static void inspect(Path source,Path target,boolean export) throws Exception {
+    if(!Files.isRegularFile(source)) throw new IOException("Missing Access database: " + source);
+    Files.createDirectories(target);
+    List<String> tables=new ArrayList<>(), queries=new ArrayList<>(), warnings=new ArrayList<>();
+    long total=0;
+    try(Database db=new DatabaseBuilder(source.toFile()).setReadOnly(true).open()) {
+      int serial=0;
+      for(String name:db.getTableNames()) {
+        Table table=db.getTable(name);
+        String file=String.format(Locale.ROOT,"table-%04d.jsonl",++serial);
+        List<String> cols=new ArrayList<>(), keys=new ArrayList<>();
+        boolean complex=false, lacksPk=true;
+        for(Column c:table.getColumns()) {
+          String t=c.getType().name();
+          if(t.equals("COMPLEX_TYPE") || t.equals("UNKNOWN_0D") || t.equals("UNSUPPORTED_VARLEN")) complex=true;
+          cols.add("{\"name\":" + j(c.getName()) + ",\"type\":" + j(t) + ",\"length\":" + c.getLength() + ",\"auto_number\":"+c.isAutoNumber()+"}");
+        }
+        for(Index idx:table.getIndexes()) {
+          List<String> names=new ArrayList<>();
+          for(Index.Column c:idx.getColumns()) names.add(j(c.getName()));
+          keys.add("{\"name\":"+j(idx.getName())+",\"primary\":"+idx.isPrimaryKey()+",\"unique\":"+idx.isUnique()+",\"columns\":"+array(names)+"}");
+          if(idx.isPrimaryKey()) lacksPk=false;
+        }
+        if(lacksPk) warnings.add("No primary key: " + name + "; retain source ordinals for duplicates");
+        if(complex) warnings.add("Complex/attachment field: " + name + "; inspection only; export may require Access on Windows");
+        long count=0;
+        Path dest=target.resolve(file);
+        try(BufferedWriter out=export ? Files.newBufferedWriter(dest,StandardCharsets.UTF_8) : null) {
+          for(Row row:table) {
+            count++;
+            if(export) {
+              List<String> values=new ArrayList<>();
+              for(Column col:table.getColumns()) {
+                try { values.add(val(row.get(col.getName()))); }
+                catch(Exception ex) { throw new IOException("Unsupported value at " + name + " row " + count + " column " + col.getName() + ": " + ex.getMessage(),ex); }
+              }
+              out.write(array(values)); out.newLine();
+            }
+          }
+        }
+        total+=count;
+        String data=export?",\"data_file\":"+j(file)+",\"sha256\":"+j(sha(dest)):"";
+        tables.add("{\"name\":"+j(name)+",\"rows\":"+count+",\"columns\":"+array(cols)+",\"indexes\":"+array(keys)+data+"}");
+      }
+      try {
+        for(Query q:db.getQueries()) {
+          String sql;
+          try { sql=q.toSQLString(); } catch(RuntimeException ex) { sql=null; warnings.add("Unparsable saved query: " + q.getName()); }
+          queries.add("{\"name\":"+j(q.getName())+",\"type\":"+j(q.getType().toString())+",\"sql\":"+(sql==null?"null":j(sql))+"}");
+        }
+      } catch(Exception ex) { warnings.add("Unable to inventory saved queries: " + ex.getClass().getSimpleName()); }
+      List<String> warningsJson=new ArrayList<>(); for(String s:warnings) warningsJson.add(j(s));
+      String schema="{\"format\":\"access-fieldkit-v1\",\"source_name\":"+j(source.getFileName().toString())+
+        ",\"file_sha256\":"+j(sha(source))+",\"access_format\":"+j(db.getFileFormat().name())+
+        ",\"exported\":"+export+",\"tables\":"+array(tables)+",\"queries\":"+array(queries)+
+        ",\"total_rows\":"+total+",\"warnings\":"+array(warningsJson)+"}";
+      Files.writeString(target.resolve("manifest.json"),schema+"\n",StandardCharsets.UTF_8);
+      System.out.println("Access read-only " + (export ? "export" : "inspection") + ": " + tables.size() + " tables, " + total + " rows, " + queries.size() + " queries");
+    }
+  }
+  public static void main(String[] args) throws Exception {
+    TimeZone.setDefault(TimeZone.getTimeZone("UTC"));
+    if(args.length!=3 || !(args[0].equals("inspect") || args[0].equals("export")))
+      throw new IllegalArgumentException("Usage: AccessReader inspect|export source.accdb output-directory");
+    inspect(Paths.get(args[1]),Paths.get(args[2]),args[0].equals("export"));
+  }
+}

access_fieldkit/landing.py

@@ -0,0 +1,208 @@
+"""Loss-aware SQLite landing zone: preserves source ordinals and duplicate rows.
+
+This is staging, not an automatic normalized schema conversion. No source keys or
+foreign keys are invented; duplicate and orphaned records remain inspectable.
+"""
+import base64
+import hashlib
+import json
+import os
+import sqlite3
+import tempfile
+from pathlib import Path
+
+
+def quote(name):
+    if not isinstance(name, str) or '\x00' in name or not name:
+        raise ValueError(f"Invalid SQL identifier: {name!r}")
+    return '"' + name.replace('"', '""') + '"'
+
+
+def read_manifest(folder, require_export=True):
+    folder = Path(folder)
+    manifest = json.loads((folder / 'manifest.json').read_text(encoding='utf-8'))
+    if manifest.get('format') != 'access-fieldkit-v1':
+        raise ValueError('Unrecognized export format')
+    if require_export and not manifest.get('exported'):
+        raise ValueError('Only an inventory was supplied; run export first')
+    ids = [t['name'].casefold() for t in manifest['tables']]
+    if len(ids) != len(set(ids)):
+        raise ValueError('Duplicate case-insensitive table names')
+    for t in manifest['tables']:
+        names = [c['name'].casefold() for c in t['columns']]
+        if len(names) != len(set(names)):
+            raise ValueError(f"Duplicate column names in {t['name']}")
+        if require_export:
+            data_file = t['data_file']
+            if data_file != Path(data_file).name or not data_file.startswith('table-') or not data_file.endswith('.jsonl'):
+                raise ValueError('Unsafe data file path in export manifest')
+    return manifest
+
+
+def check_checksum(path, expected):
+    digest = hashlib.sha256()
+    with Path(path).open('rb') as f:
+        for block in iter(lambda: f.read(1024 * 1024), b''):
+            digest.update(block)
+    got = digest.hexdigest()
+    if got != expected:
+        raise ValueError(f'Data checksum mismatch: {path.name} (expected {expected}, got {got})')
+    return got
+
+
+def iter_rows(folder, table):
+    source = Path(folder) / table['data_file']
+    with source.open(encoding='utf-8', newline='') as f:
+        for line_num, line in enumerate(f, 1):
+            if not line.strip():
+                raise ValueError(f'Blank source record: {source}:{line_num}')
+            row = json.loads(line)
+            if not isinstance(row, list) or len(row) != len(table['columns']):
+                raise ValueError(f'Invalid source record: {source}:{line_num}')
+            yield line_num, row
+
+
+def decode(value):
+    if isinstance(value, dict):
+        if len(value) != 1:
+            raise ValueError('Unknown tagged Access value')
+        tag, raw = next(iter(value.items()))
+        if not isinstance(raw, str):
+            raise ValueError('Malformed tagged Access value')
+        if tag == '$binary':
+            return base64.b64decode(raw, validate=True)
+        if tag == '$decimal':
+            # SQLite has no exact decimal storage class. Use TEXT without
+            # losing the Access Currency value's original decimal scale.
+            return raw
+        if tag == '$float':
+            return float(raw)
+        raise ValueError(f'Unsupported tagged Access value: {tag}')
+    if isinstance(value, (list, dict)):
+        raise ValueError('Nested Access value must be extracted explicitly')
+    return value
+
+
+def dtype(access_type):
+    if access_type in ('BYTE', 'INT', 'LONG', 'BIG_INT', 'SHORT', 'BOOLEAN'):
+        return 'INTEGER'
+    if access_type in ('DOUBLE', 'FLOAT'):
+        return 'REAL'
+    if access_type in ('BINARY', 'OLE'):
+        return 'BLOB'
+    return 'TEXT'
+
+
+def load(folder, target, force=False):
+    folder, target = Path(folder), Path(target)
+    manifest = read_manifest(folder)
+    if target.exists() and not force:
+        raise FileExistsError(f'{target} exists (use --force to replace a disposable target)')
+    if target.is_symlink():
+        raise ValueError('Refusing to replace a symlink target')
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmpname = tempfile.mkstemp(prefix='.access-fieldkit-', suffix='.sqlite', dir=target.parent)
+    os.close(fd)
+    tmp = Path(tmpname)
+    conn = None
+    stats = []
+    try:
+        conn = sqlite3.connect(tmp)
+        conn.execute('PRAGMA journal_mode=DELETE')
+        conn.execute('PRAGMA synchronous=FULL')
+        conn.execute('CREATE TABLE _af_metadata (table_name TEXT PRIMARY KEY, ordinal_field TEXT NOT NULL, data_file TEXT NOT NULL, sha256 TEXT NOT NULL)')
+        for table in manifest['tables']:
+            name = table['name']
+            columns = table['columns']
+            ordinal = '_af_source_row'
+            existing = {c['name'].casefold() for c in columns}
+            while ordinal.casefold() in existing:
+                ordinal += '_'
+            fields = [quote(ordinal) + ' INTEGER PRIMARY KEY']
+            fields += [quote(c['name']) + ' ' + dtype(c['type']) for c in columns]
+            if name.casefold() == '_af_metadata':
+                raise ValueError('Source table name collides with internal metadata table')
+            conn.execute('CREATE TABLE ' + quote(name) + ' (' + ','.join(fields) + ')')
+            check_checksum(folder / table['data_file'], table['sha256'])
+            placeholders = ','.join('?' for _ in range(len(columns)+1))
+            insert = 'INSERT INTO ' + quote(name) + ' VALUES (' + placeholders + ')'
+            count = 0
+            batch = []
+            for num, values in iter_rows(folder, table):
+                batch.append([num, *(decode(v) for v in values)])
+                if len(batch) >= 500:
+                    conn.executemany(insert, batch)
+                    batch.clear()
+                count += 1
+            if batch:
+                conn.executemany(insert, batch)
+            if count != table['rows']:
+                raise ValueError(f'Row-count mismatch for {name}: {count} != {table["rows"]}')
+            conn.execute('INSERT INTO _af_metadata VALUES (?,?,?,?)', (name, ordinal, table['data_file'], table['sha256']))
+            stats.append({'name':name,'rows':count})
+        conn.commit()
+        conn.close()
+        conn = None
+        # An atomic replacement keeps any prior target intact on a failed load.
+        os.replace(tmp, target)
+        return {'target':str(target),'tables':len(stats),'rows':sum(x['rows'] for x in stats),'status':'loaded','detail':stats}
+    finally:
+        if conn is not None:
+            conn.close()
+        if tmp.exists():
+            tmp.unlink()
+
+
+def reconcile(folder, target):
+    folder, target = Path(folder), Path(target)
+    manifest = read_manifest(folder)
+    issues = []
+    total = 0
+    with sqlite3.connect(f'file:{target.resolve()}?mode=ro', uri=True) as conn:
+        try:
+            mappings = {name:(ordinal,filename,digest) for name,ordinal,filename,digest in conn.execute('SELECT * FROM _af_metadata')}
+        except sqlite3.Error as ex:
+            raise ValueError('Not an access-fieldkit SQLite landing database') from ex
+        if set(mappings) != {t['name'] for t in manifest['tables']}:
+            issues.append('Table inventory differs between source export and target')
+        for table in manifest['tables']:
+            name = table['name']
+            if name not in mappings:
+                continue
+            ordinal,filename,digest=mappings[name]
+            try:
+                check_checksum(folder/table['data_file'],table['sha256'])
+                if digest!=table['sha256'] or filename!=table['data_file']:
+                    issues.append(f'{name}: source fingerprint does not match landing metadata')
+                got = conn.execute('SELECT * FROM ' + quote(name) + ' ORDER BY ' + quote(ordinal))
+                count = 0
+                for (num,source), row in zip(iter_rows(folder,table),got):
+                    gotordinal,*values = row
+                    if gotordinal!=num:
+                        issues.append(f'{name}: row ordinal mismatch at {num}')
+                    for col,original,actual in zip(table['columns'],source,values):
+                        expected=decode(original)
+                        if isinstance(expected,float):
+                            equal = expected == actual
+                        else:
+                            equal = expected == actual and type(expected) is type(actual)
+                            # SQLite stores Boolean as 0/1 rather than bool.
+                            if isinstance(expected,bool):
+                                equal = int(expected) == actual
+                        if not equal:
+                            issues.append(f'{name}: value mismatch row {num} column {col["name"]}')
+                        if len(issues)>=20:
+                            break
+                    count+=1
+                    if len(issues)>=20:
+                        break
+                count_db=conn.execute('SELECT COUNT(*) FROM '+quote(name)).fetchone()[0]
+                if count_db!=table['rows'] or count!=table['rows']:
+                    issues.append(f'{name}: source={table["rows"]} compared={count} target={count_db}')
+                total+=count_db
+            except (ValueError,sqlite3.Error) as ex:
+                issues.append(f'{name}: {ex}')
+            if len(issues)>=20:
+                break
+    return {'valid':not issues,'source_file_sha256':manifest['file_sha256'],'tables':len(manifest['tables']),
+            'rows':total,'issues':issues[:25]}

access_fieldkit/runtime.py

@@ -0,0 +1,51 @@
+"""Prepare the pinned Java extractor on a local machine."""
+import hashlib
+import os
+import subprocess
+import urllib.request
+from pathlib import Path
+
+VERSION = "5.0.4"
+# Checked against the JAR used in the Oracle VM run and the upstream release.
+SHA256 = "19a7494a56f439a57fda85c059b019b665802085cec5ae8186d1e028cc1bdfbc"
+URL = f"https://repo.maven.apache.org/maven2/com/healthmarketscience/jackcess/jackcess/{VERSION}/jackcess-{VERSION}.jar"
+CACHE = Path.home() / ".cache" / "access-fieldkit" / VERSION
+JAVA_SOURCE = Path(__file__).parent / "java" / "AccessReader.java"
+
+
+def java_classpath(jar=None):
+    cache = CACHE
+    cache.mkdir(parents=True, exist_ok=True)
+    if jar is not None:
+        dependency = Path(jar).resolve()
+        if not dependency.is_file():
+            raise FileNotFoundError(f"Jackcess jar not found: {dependency}")
+    else:
+        dependency = cache / f"jackcess-{VERSION}.jar"
+        if not dependency.exists():
+            data = urllib.request.urlopen(URL, timeout=45).read()
+            if not data.startswith(b"PK"):
+                raise RuntimeError("Downloaded dependency was not a JAR")
+            if hashlib.sha256(data).hexdigest() != SHA256:
+                raise RuntimeError("Jackcess download failed SHA-256 verification")
+            temp = dependency.with_suffix(".tmp")
+            temp.write_bytes(data)
+            temp.replace(dependency)
+    if hashlib.sha256(dependency.read_bytes()).hexdigest() != SHA256:
+        raise RuntimeError("Jackcess JAR checksum mismatch: " + str(dependency))
+    stamp = hashlib.sha256(JAVA_SOURCE.read_bytes() + str(dependency).encode() +
+                           str(dependency.stat().st_size).encode()).hexdigest()
+    classes = cache / "classes"
+    marker = cache / "compile.sha256"
+    if not (classes / "AccessReader.class").exists() or not marker.exists() or marker.read_text() != stamp:
+        classes.mkdir(exist_ok=True)
+        subprocess.run(["javac", "-encoding", "UTF-8", "-cp", str(dependency), "-d",
+                        str(classes), str(JAVA_SOURCE)], check=True)
+        marker.write_text(stamp)
+    return os.pathsep.join((str(classes), str(dependency)))
+
+
+def run_reader(mode, source, target, jar=None):
+    cp = java_classpath(jar)
+    subprocess.run(["java", "-cp", cp, "AccessReader", mode,
+                    str(source), str(target)], check=True)

access_fieldkit/tool_probe.py

@@ -0,0 +1,70 @@
+"""Optional independent reader checks, never a claim of SSMA execution."""
+import csv
+import hashlib
+import io
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from .landing import read_manifest
+
+
+def checksum(file):
+    h=hashlib.sha256()
+    with Path(file).open('rb') as f:
+        for block in iter(lambda:f.read(1024*1024),b''):
+            h.update(block)
+    return h.hexdigest()
+
+
+def command(args,timeout=45):
+    try:
+        return subprocess.run(args,capture_output=True,text=True,timeout=timeout,check=False)
+    except (OSError,subprocess.TimeoutExpired) as ex:
+        return type('FailedProbe',(),{'returncode':-1,'stdout':'','stderr':type(ex).__name__})()
+
+
+def probe(source,folder):
+    source=Path(source)
+    m=read_manifest(folder,require_export=True)
+    if checksum(source)!=m['file_sha256']:
+        raise ValueError('Source Access file changed since export; do not compare different snapshots')
+    steps=[{'tool':'Jackcess','status':'verified','operation':'Read and export native Access data',
+            'evidence':f'{len(m["tables"])} tables, {m["total_rows"]} rows; matching original file fingerprint'}]
+    tables_exe=shutil.which('mdb-tables')
+    export_exe=shutil.which('mdb-export')
+    if not tables_exe:
+        steps.append({'tool':'MDB Tools','status':'not_run','operation':'Independent table inventory/export',
+                      'evidence':'mdb-tables executable not installed'})
+    else:
+        result=command([tables_exe,'-1',str(source)])
+        names={line.rstrip('\r') for line in result.stdout.splitlines() if line.strip()}
+        expected={t['name'] for t in m['tables']}
+        if result.returncode!=0 or names!=expected:
+            steps.append({'tool':'MDB Tools','status':'failed','operation':'Independent table inventory',
+                          'evidence':f'Exit {result.returncode}; expected {len(expected)}, saw {len(names)}; stderr={result.stderr[:200]}'})
+        else:
+            steps.append({'tool':'MDB Tools','status':'verified','operation':'Independent table inventory',
+                          'evidence':f'{len(names)} table names matched the Access inventory'})
+            candidates=[t for t in m['tables'] if t['rows']<=10000 and all(c['type'] not in ('OLE','COMPLEX_TYPE') for c in t['columns'])]
+            sample=sorted(candidates,key=lambda t:(t['rows'],t['name']))[0] if candidates else None
+            if sample and export_exe:
+                r=command([export_exe,str(source),sample['name']])
+                try:
+                    csvrows=csv.reader(io.StringIO(r.stdout,newline=''))
+                    header=next(csvrows)
+                    count=sum(1 for _ in csvrows)
+                    match=(r.returncode==0 and count==sample['rows'] and header==[c['name'] for c in sample['columns']])
+                except (ValueError,csv.Error,StopIteration):match=False;count=-1
+                steps.append({'tool':'MDB Tools','status':'verified' if match else 'failed',
+                              'operation':'Independent CSV export of '+sample['name'],
+                              'evidence':f'Expected {sample["rows"]} rows; got {count}. Headers also compared. This does not prove full type fidelity.'})
+            else:
+                steps.append({'tool':'MDB Tools','status':'not_run','operation':'Independent CSV export',
+                              'evidence':'No suitable small table or mdb-export not installed'})
+    steps.append({'tool':'Microsoft SSMA for Access','status':'not_run',
+                  'operation':'Windows assessment / SQL Server schema and data conversion',
+                  'evidence':'Requires actual SSMA execution on Windows with Access/ACE and SQL Server/Azure SQL'})
+    return {'file_sha256':m['file_sha256'],'probes':steps,
+            'note':'Verified applies only to the stated operation; it does not establish application or VBA migration success.'}

access_fieldkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: access-fieldkit
+Version: 0.1.0
+Summary: Read-only Access database inventory, loss-aware export, and migration reconciliation
+Author: mhatipog
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mhatipog/access-migration-fieldkit
+Project-URL: Issues, https://github.com/mhatipog/access-migration-fieldkit/issues
+Project-URL: Changelog, https://github.com/mhatipog/access-migration-fieldkit/blob/main/CHANGELOG.md
+Keywords: microsoft-access,accdb,mdb,migration,sqlite,database
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Java
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Access Fieldkit
+
+Tools for the first awkward week of an Access migration: finding out what's in the file, getting the rows out without quietly changing them, and checking that a landing copy still matches.
+
+The most common mistake is treating a row count as a completed migration. An Access database can carry keyless tables, embedded SQL tied to forms, four-decimal Currency values, unsaved business rules in VBA, and paths to files that don't live in the database. Moving tables doesn't fix any of that.
+
+Fieldkit does **not** claim to convert an Access application. It's a read-only source inspector, exporter, SQLite staging loader, and per-value reconciliation tool. It also includes a PostgreSQL loading example and a runbook for SQL Server/SSMA migrations.
+
+## Quick start
+
+Requires Python 3.10+, Java JDK 11+, and an Internet connection for the first run to retrieve Jackcess 5.0.4 from Maven Central. The downloaded JAR is checked against the pinned SHA-256. You can also pass a verified local JAR with `--jackcess-jar`.
+
+```bash
+python -m pip install .
+
+# Makes only a manifest. Does not export rows.
+access-fieldkit inspect ./legacy.accdb --out ./work/inventory
+
+# Copies table rows into numbered JSONL files, plus a manifest with SHA-256 checksums.
+access-fieldkit export ./legacy.accdb --out ./work/export
+
+# What will need attention before someone changes the database or its front end?
+access-fieldkit assess ./work/export --out ./work/assessment.md
+
+# Optional: compare the native inventory with MDB Tools, if installed.
+access-fieldkit probe-tools ./legacy.accdb ./work/export --out ./work/tool-probes.json
+
+# Creates a new disposable landing database with original table/column names.
+access-fieldkit load-sqlite ./work/export ./work/landing.sqlite
+
+# Compares every exported value to the SQLite landing copy.
+access-fieldkit reconcile ./work/export ./work/landing.sqlite
+```
+
+Both `inspect` and `export` open the Access file **read-only**. Existing output folders are not overwritten. The SQLite loader creates its target through a temporary file and refuses to replace an existing database unless `--force` is given; don't point it at production.
+
+## What the export contains
+
+`manifest.json` records original table and column names, Access field types, indexes, row counts, saved queries when readable, the source file checksum, and individual table-file checksums. Each `table-0001.jsonl` holds one row per line in the original column order. The file names are numbered on purpose: original Access object names must never become unchecked filesystem paths.
+
+Raw rows are kept in order. No artificial primary keys are introduced into source data, no duplicates are collapsed, and NULL is different from an empty string. Currency and decimal values use an explicit text tag so that an intermediate JSON float never rounds the number. Binary values use base64. Unsupported object values cause extraction to fail with a table/row/column location rather than disappear.
+
+The SQLite target is a **landing zone**, not a finalized relational schema: it retains every original column and adds an internal source-row ordinal. Access Currency maps to SQLite TEXT, because SQLite has no exact fixed-decimal type. Use a deliberate target schema and business-approved conversions before building a production application.
+
+## Where it fits
+
+- **SQLite / local web API:** Run `load-sqlite`, then see `examples/serve_sqlite.py` for a read-only local HTTP view of the landing tables.
+- **PostgreSQL:** `examples/load_postgres.py` uses psycopg 3 to create a fresh schema and load the extracted values, including Currency as `NUMERIC(19,4)`.
+- **SQL Server / Azure SQL:** Use SSMA for the bulk SQL Server path; apply the decisions in [guides/sql-server.md](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/sql-server.md). This repository does not pretend to be SSMA.
+- **Modern application rewrite:** Inventory saved queries here. Use desktop Access on Windows to document forms, events, macros and VBA before moving those workflows into an API or new UI.
+
+## Guides
+
+- [Start with an inventory](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/inventory.md)
+- [Currency, NULLs, dates and difficult data](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/data-fidelity.md)
+- [Saved queries, VBA and forms](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/application-rewrite.md)
+- [SQL Server and SSMA](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/sql-server.md)
+- [PostgreSQL landing](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/postgresql.md)
+- [Cutover and rollback](https://github.com/mhatipog/access-migration-fieldkit/blob/main/guides/cutover.md)
+
+## Limits worth knowing
+
+Encrypted `.accdb` files may need additional codec support; this tool doesn't try to bypass encryption. Attachments, multivalue columns, linked tables, and Access UI objects require separate inspection. If an Access object is unsupported, don't interpret an incomplete export as proof of a complete application migration. A Windows Access/SSMA run remains necessary for those parts.
+
+This code grew out of repeatable migrations of real-format ACE files and documented Microsoft/Jackcess limitations, **not production client migrations**. The included examples use made-up data only. Use backups, permission reviews and a write freeze when assessing an actual customer database.
+
+MIT licensed. See [LICENSE](https://github.com/mhatipog/access-migration-fieldkit/blob/main/LICENSE).
+
+Maintained by [Vecture](https://vecture.be). Contributions and field reports are welcome via [GitHub issues](https://github.com/mhatipog/access-migration-fieldkit/issues).

access_fieldkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+access_fieldkit/__init__.py,sha256=A0RGaDxI_an1bZ0GDjZ9l4BbCLxsS9ZLM8EWhSD0wy0,99
+access_fieldkit/__main__.py,sha256=XK7K-spEyRCZvijkqt01OxhALwtUj6YbiBUaddwVgY0,3526
+access_fieldkit/assessment.py,sha256=C6rVPkOQ8GMPMQo_sRtTDsAhs5WoKgtVpvYTS9OmoCY,4432
+access_fieldkit/landing.py,sha256=4TbzEnsqNjCNds3AcZFkNjoZQE0dNYO0dHuETLc6sTc,9443
+access_fieldkit/runtime.py,sha256=0HqAaEbN0w5a46Zx1ZzdmCquTpqQzG1FFadJlAfOPcM,2368
+access_fieldkit/tool_probe.py,sha256=p2Qfk93f_HPTNQ7mj-fAv4ln4QcU_kvi5O9eKq_ayx0,3920
+access_fieldkit/java/AccessReader.java,sha256=451q9DYhDEhTt5vNxs-XazPLMalp-t60FlyLH7jllOs,6983
+access_fieldkit-0.1.0.dist-info/licenses/LICENSE,sha256=CckmNAppbhFcpzS2419m_uEW4CYTGP2CL06CbQAeDgA,1065
+access_fieldkit-0.1.0.dist-info/METADATA,sha256=i8d88GHV1Ap8ggn-LyoWXax0JCDzbFTG6iLlaYV-VOY,6748
+access_fieldkit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+access_fieldkit-0.1.0.dist-info/entry_points.txt,sha256=ZFcSD9VoXHr2jD57ctdifxryWxZFLJL3G1YNuTShgG8,66
+access_fieldkit-0.1.0.dist-info/top_level.txt,sha256=dVaFN4ct99tAR5mTtkGQcAny_TxD6_NWLxJ99sGpG9M,16
+access_fieldkit-0.1.0.dist-info/RECORD,,

access_fieldkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

access_fieldkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+access-fieldkit = access_fieldkit.__main__:main

access_fieldkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mhatipog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

access_fieldkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+access_fieldkit