@dforge-core/dforge-mcp 0.2.44 → 0.2.46-next

package/skills/dforge-1c-import/scripts/1c.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+One way in, so the split between library and project stays a fact rather than a habit.
+
+    python tools/1c.py <command> [args...]
+    python tools/1c.py --list          # what there is
+    python tools/1c.py --boundary      # does the library still stand on its own?
+
+`tools/lib` is 1C and dForge: how a configuration is stored, how its metadata parses,
+what the physical tables mean, and how rows are copied and checked. It is meant to be
+lifted out and pointed at a different infobase.
+
+`tools/project` is this infobase: which object belongs to which module, which 1C column
+feeds each ported one, which regulated statements it holds, this company's own proper
+nouns, and the modules written by hand. `DF1C_PROJECT` points the library at a different
+one; `binding.py` lists the whole of what a project has to provide.
+
+Both directories go on the path, so the modules import each other by plain name and a
+move between them costs no edits. That convenience is also the hazard, so `--boundary`
+checks two things rather than trusting either: that no library module IMPORTS a project
+one, and that no library module NAMES this project's world - its server, its infobase,
+its tenant, its company's abbreviations. A literal is the quiet way to bind a library to
+one configuration, and it is how `DF1C_DB` came to default to `utp_biscuit` for months.
+
+Because both directories are on one path, a project module may not take a name the
+library already uses: `regulated.py` rather than `forms.py`, `vocabulary.py` rather than
+`terms.py`. `--boundary` catches the shadowing as an import crossing.
+"""
+from __future__ import print_function
+
+import io
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+LIB = os.path.join(HERE, "lib")
+PROJECT = os.path.abspath(os.environ.get("DF1C_PROJECT") or os.path.join(HERE, "project"))
+
+for entry in (PROJECT, LIB):
+	if entry not in sys.path:
+		sys.path.insert(0, entry)
+
+
+def commands():
+	"""Every runnable module, library or project, mapped to (path, first docstring line)."""
+	found = {}
+	for directory in (LIB, PROJECT):
+		for name in sorted(os.listdir(directory)):
+			if not name.endswith(".py") or name.startswith("_") or name[:-3] in found:
+				continue
+			path = os.path.join(directory, name)
+			summary = _runnable(path)
+			if summary is not None:
+				found[name[:-3]] = (path, summary)
+	return found
+
+
+def _runnable(path):
+	"""The module's first docstring line if it can be run as a script, else None."""
+	with io.open(path, encoding="utf-8") as f:
+		text = f.read()
+	# Anything runnable: most define main(), a few only a __main__ block.
+	if "def main(" not in text and "__name__" not in text:
+		return None
+	if '"""' not in text:
+		return ""
+	body = text.split('"""', 2)[1].strip().splitlines()
+	return (body[0] if body else "").strip()
+
+
+def boundary():
+	"""Two ways the library can stop standing on its own, both read off the source.
+
+	IMPORTS. The path puts both directories in reach, so nothing stops a library module
+	importing `contours` directly and nothing would complain until someone tried to lift
+	the library out.
+
+	NAMES. An import is the loud way to bind to one infobase; a literal is the quiet one.
+	`DF1C_DB` defaulting to `utp_biscuit` and `DF_TENANT` to `hbf1` sat in the library for
+	a long while, harmless with one infobase and a trap with two - point the tools at a
+	second configuration, forget one variable, and they read the first one with
+	right-looking output. So the names of THIS project's world are refused in the library,
+	including in its comments, since a stale comment is how the next reader learns the
+	wrong thing.
+
+	The list is read from the project rather than written here, so a project that renames
+	itself does not have to remember this file.
+	"""
+	import ast
+	import re
+
+	project_modules = set(n[:-3] for n in os.listdir(PROJECT) if n.endswith(".py"))
+
+	# What this project calls itself: the infobase, the tenant and its own proper nouns.
+	reserved = set()
+	for variable in ("DF1C_DB", "DF1C_SERVER", "DF_TENANT"):
+		value = os.environ.get(variable)
+		if value:
+			reserved.add(value.lower())
+	env_example = os.path.join(os.path.dirname(os.path.abspath(PROJECT)), os.pardir,
+	                           ".env.example")
+	if os.path.exists(env_example):
+		with io.open(env_example, encoding="utf-8") as f:
+			for line in f:
+				match = re.match(r"\s*(DF1C_DB|DF1C_SERVER|DF_TENANT)\s*=\s*(\S+)", line)
+				if match:
+					reserved.add(match.group(2).lower())
+	terms = os.path.join(PROJECT, "terms.py")
+	if os.path.exists(terms):
+		with io.open(terms, encoding="utf-8") as f:
+			for value in re.findall(r'u"([^"]+)"\s*:', f.read()):
+				if len(value) > 3:      # two- and three-letter forms collide with real words
+					reserved.add(value.lower())
+
+	problems = []
+	for name in sorted(os.listdir(LIB)):
+		if not name.endswith(".py"):
+			continue
+		with io.open(os.path.join(LIB, name), encoding="utf-8") as f:
+			text = f.read()
+		tree = ast.parse(text)
+		for node in ast.walk(tree):
+			named = []
+			if isinstance(node, ast.Import):
+				named = [a.name.split(".")[0] for a in node.names]
+			elif isinstance(node, ast.ImportFrom) and node.module:
+				named = [node.module.split(".")[0]]
+			for target in named:
+				if target in project_modules:
+					problems.append("lib/%s imports %s - go through binding.py instead"
+					                % (name, target))
+		# paths.py explains why these names are refused, so it is allowed to name them.
+		if name == "paths.py":
+			continue
+		lowered = text.lower()
+		for word in sorted(reserved):
+			if word in lowered:
+				problems.append("lib/%s names %r - that is the project's, not the library's"
+				                % (name, word))
+	return problems
+
+
+def main():
+	args = sys.argv[1:]
+	if not args or args[0] in ("-h", "--help", "--list"):
+		import paths
+		paths.show()
+		print()
+		for name, (_, summary) in sorted(commands().items()):
+			print("  %-16s %s" % (name, summary[:60]))
+		return 0
+
+	if args[0] == "--boundary":
+		problems = boundary()
+		for line in problems:
+			print(line)
+		print("%d crossing(s) of the library/project boundary" % len(problems))
+		return 1 if problems else 0
+
+	name, rest = args[0], args[1:]
+	found = commands()
+	if name not in found:
+		print("no such command: %s (try --list)" % name)
+		return 2
+	# run_path rather than calling main(): a few tools only have a __main__
+	# block, and this runs every one of them exactly as a script would.
+	import runpy
+	sys.argv = [name] + rest
+	try:
+		runpy.run_path(found[name][0], run_name="__main__")
+	except SystemExit as stop:
+		return stop.code or 0
+	return 0
+
+
+if __name__ == "__main__":
+	sys.exit(main() or 0)

package/skills/dforge-1c-import/scripts/README.md

@@ -0,0 +1,110 @@
+# The 1C porting toolkit
+
+A Python library that reads a 1C:Enterprise 8 infobase hosted on MS SQL Server. It needs
+no 1C software and no licence. From the infobase it:
+
+- generates dForge modules;
+- copies the rows;
+- checks the result.
+
+It was built on a real port: an УТП-based configuration, 16 contours, 30 M+ rows,
+reconciled to the row and the kopeck. It is meant to be pointed at the next infobase
+unchanged.
+
+```
+scripts/
+  1c.py                 the one entry point: python 1c.py <command> [args]
+  lib/                  the library: 1C storage, metadata, generation, loading, checks
+  project-template/     what a new port starts its project package from
+```
+
+## Library and project
+
+- **`lib/` knows 1C and dForge**: how a configuration is stored, how its metadata
+  parses, what the physical tables mean, and how rows are copied and checked.
+- **The project knows this infobase**:
+  - which object goes to which module (`contours.py`);
+  - which 1C column feeds an authored column (`sources.py`);
+  - the integrator's prefixes;
+  - the hand-written modules (`authored/<module>/`).
+
+`lib/binding.py` lists everything a project may provide. Only `contours` and `sources`
+are required.
+
+**Never put project facts in `lib/`.** That covers infobase names, tenant names, the
+company's abbreviations and prefixes. `python 1c.py --boundary` checks that no library
+module imports a project module or names the project's world.
+
+**Never hand-edit generated output.** Put the change in the project, either as a spec
+override or as an authored file under `authored/<module>/` that `genmodule` merges.
+Then regenerate. If a port keeps needing hand edits, the generator is wrong.
+
+## Setup
+
+- Python 3.7+.
+- `pyodbc` and an ODBC driver for SQL Server (driver 17 or 18), to read the infobase.
+- `psycopg2`, to load and check the tenant.
+- `jsonschema`, for `validate`.
+- Node with `liquidjs` in `PRINT_NODE_DIR`, only for `printgen preview`.
+
+On Windows, set `PYTHONIOENCODING=utf-8`.
+
+Lay out a port directory and point the toolkit at it:
+
+```
+myport/
+  .env                  credentials (never committed)
+  project/              copied from project-template/, then filled in
+  out/                  what the extraction writes (DF1C_OUT, default <root>/out)
+  modules/              generated modules (DF1C_MODULES, default <root>/modules)
+```
+
+```
+DF1C_ROOT=/path/to/myport
+DF1C_PROJECT=/path/to/myport/project
+DF1C_SERVER=<sql server>   DF1C_DB=<infobase db>   DF1C_USER= DF1C_PASS=   # read-only login; Windows auth when USER is empty
+DF_TENANT=<tenant code>    DF_PG_HOST= DF_PG_PORT= DF_PG_USER= DF_PG_PASS=  # the tenant's Postgres, for load and checks
+```
+
+None of these has a default. A default that named one infobase would make the toolkit
+quietly read or write that infobase when a variable was forgotten.
+
+## The pipeline
+
+Each step reads what the previous one wrote to `out/`. Every command has `--help` or a
+docstring with its options, and `python 1c.py --list` lists them all.
+
+| # | step | command |
+|---|---|---|
+| 1 | Read the configuration and DBNames from the SQL tables | `dump1c probe` · `dump1c dbnames` · `dump1c schema` · `dump1c extract` |
+| 2 | Parse the metadata, resolve type GUIDs, join the physical schema | `meta allobjects` · `typemap` · `analyze` · `attrs <Object>` · `explore <Object>` |
+| 3 | Extract the module texts (posting handlers, print procedures) | `extract_code` · `unpack <Object> --code` |
+| 4 | Inventory: what exists, what is used, what is the client's | `inventory` · `docusage` · `custom` · `sizing` · `subsystems` |
+| 5 | Read the posting handlers: which registers each document writes and from where | `handlers [--client]` · `callgraph` · `recorders` · `recorded` · `idioms` · `spec` |
+| 6 | Decide the module boundaries | `subsystems --contours --acyclic`, copied into `project/contours.py` and corrected |
+| 7 | Generate and validate the modules | `autospec [module]` · `genmodule` · `validate` · `deps` · `layers` |
+| 8 | Install them | `npx -y @dforge-core/dforge-cli@latest module install ...`, or `rebuild --code <tenant> --install` |
+| 9 | Copy the rows and reconcile | `migrate plan\|check\|run\|verify\|fill <module>` · `integrity` · `columnmap <module>` |
+| 10 | Post state and registers | `posted [--mark]` · `posting` · `seedstate` · `totals` · `coverage` |
+| 11 | Catch up with what 1C changed | `delta --baseline` · `delta [--apply]` |
+| 12 | Print forms and reports | `mxl list [--client]` · `mxl dump <Object>` · `printgen <spec>` · `printgen preview <spec> <form> <key>` · `reportgen <spec>` |
+| 13 | External reports and processings stored in the infobase | `external` |
+
+`rebuild --code <tenant>` runs steps 8–10 from nothing, which makes a tenant
+reproducible.
+
+## Rules the toolkit assumes
+
+- **The infobase is read-only.** Use a SELECT-only login.
+- **Open ad-hoc database connections in autocommit.** A read transaction left open
+  blocks the next install's `ALTER`.
+- **Resolve a physical column (`_FldNNN`) only through DBNames** (`attrs`, `columnmap`).
+  Never resolve it by cardinality.
+- **Stop on a 401 from the tenant.** Ask for a fresh login, then re-run
+  `posted --mark` for documents loaded in the meantime.
+
+## Source
+
+This copy is kept in step with the port it was developed on (`tools/lib`, `tools/1c.py`
+there). Fixes made in a port go back to the library here. A project's own files never
+come here.

package/skills/dforge-1c-import/scripts/lib/analyze.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Join the physical schema against DBNames to see which parts of the configuration
+the client actually uses. A stock UTP ships hundreds of catalogs and documents;
+only the populated ones are worth porting.
+"""
+import codecs
+import collections
+import json
+import os
+import re
+import sys
+
+import paths
+
+OUT = paths.OUT
+
+# Physical table families that carry business data, in the order we care about.
+DATA_KINDS = ("Reference", "Document", "InfoRg", "AccumRg", "AccRg", "Chrc", "Acc",
+              "Enum", "DocumentJournal", "Node", "BPr", "Task", "Const")
+
+SPLIT = re.compile(r"^_([A-Za-z]+?)(\d+)(?:_(.+))?$")
+
+
+def load(name):
+	with codecs.open(os.path.join(OUT, name), "r", "utf-8") as f:
+		return json.load(f)
+
+
+def classify(table_name):
+	"""_Document123_VT456 -> ('Document', 123, 'VT456')"""
+	m = SPLIT.match(table_name)
+	if not m:
+		return None, None, None
+	return m.group(1), int(m.group(2)), m.group(3)
+
+
+def main():
+	schema = load("schema.json")
+	tables = {t["name"]: t for t in schema["tables"]}
+
+	summary = collections.OrderedDict((k, {"tables": 0, "used": 0, "rows": 0}) for k in DATA_KINDS)
+	detail = collections.defaultdict(list)
+
+	for name, t in tables.items():
+		kind, number, suffix = classify(name)
+		if kind not in summary or suffix:          # skip tabular sections, roll them up separately
+			continue
+		rows = t["rows"] or 0
+		# a document's tabular sections belong to the document's footprint
+		child_rows = sum((tables[n]["rows"] or 0) for n in tables
+		                 if n.startswith("_%s%d_" % (kind, number)))
+		summary[kind]["tables"] += 1
+		summary[kind]["rows"] += rows
+		if rows:
+			summary[kind]["used"] += 1
+		detail[kind].append({"table": name, "number": number, "rows": rows,
+		                     "childRows": child_rows, "columns": len(t["columns"])})
+
+	print("%-18s %8s %8s %14s" % ("kind", "tables", "used", "rows"))
+	print("-" * 52)
+	for kind, s in summary.items():
+		if s["tables"]:
+			print("%-18s %8d %8d %14s" % (kind, s["tables"], s["used"], "{:,}".format(s["rows"])))
+
+	top = int(sys.argv[1]) if len(sys.argv) > 1 else 25
+	for kind in ("Document", "Reference", "AccumRg", "InfoRg"):
+		rows = sorted(detail[kind], key=lambda d: -(d["rows"] + d["childRows"]))[:top]
+		print("\n== %s: top %d by volume ==" % (kind, top))
+		for d in rows:
+			if not (d["rows"] or d["childRows"]):
+				continue
+			print("   %-22s rows=%-12s child=%-12s cols=%d"
+			      % (d["table"], "{:,}".format(d["rows"]),
+			         "{:,}".format(d["childRows"]), d["columns"]))
+
+	with codecs.open(os.path.join(OUT, "usage.json"), "w", "utf-8") as f:
+		json.dump({"summary": summary, "detail": detail}, f, ensure_ascii=False, indent="\t")
+
+
+if __name__ == "__main__":
+	main()

package/skills/dforge-1c-import/scripts/lib/attrs.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Extract the field list of a metadata object, with references resolved.
+
+Every typed thing in a 1C object file - a catalog attribute, a register dimension
+or resource, a tabular-section column - is encoded the same way:
+
+    ["2", ["1", ["0","0",<own guid>], "<Name>", ["1","ru","<Synonym>"], ...],
+          ["Pattern", <type...>]]
+
+so the collector looks for that shape anywhere in the tree rather than hard-coding
+per-kind offsets, and takes the nearest named ancestor as the tabular section.
+
+    python attrs.py <ObjectName>              one object, to the console
+    python attrs.py --model <file> <names...> several objects, to a markdown file
+"""
+from __future__ import print_function
+
+import codecs
+import json
+import os
+import paths
+import sys
+
+import meta
+
+OUT = meta.OUT
+
+PRIMITIVE = {"S": "string", "N": "number", "B": "bool", "D": "date"}
+
+# Collection class GUIDs -> what the fields in them mean, confirmed by checking a
+# register whose meaning is unambiguous (ТоварыНаСкладах: Количество is the resource,
+# Склад/Номенклатура the dimensions). Unknown GUIDs print truncated so they show up.
+ROLE = {
+	"cf4abea7-37b2-11d4-940f-008048da11f9": "attr",        # catalog attribute
+	"45e46cbc-3e24-4165-8b7b-cc98a6f80211": "attr",        # document attribute
+	"888744e1-b616-11d4-9436-004095e12fc7": "column",      # tabular section column
+	"b64d9a41-1642-11d6-a3c7-0050bae0a776": "resource",    # accumulation register
+	"b64d9a42-1642-11d6-a3c7-0050bae0a776": "attr",
+	"b64d9a43-1642-11d6-a3c7-0050bae0a776": "dimension",
+	"13134202-f60b-11d5-a3c7-0050bae0a776": "resource",    # information register
+	"13134203-f60b-11d5-a3c7-0050bae0a776": "dimension",
+	"13134204-f60b-11d5-a3c7-0050bae0a776": "attr",
+}
+
+ROLE_ORDER = ("dimension", "resource", "attr", "column")
+
+
+def is_identity(node):
+	"""["1", ["0","0",<guid>], "<Name>", ["1","ru","<Synonym>"], "", "0", "0"]"""
+	if not (isinstance(node, list) and len(node) >= 3 and isinstance(node[1], list)):
+		return False
+	if len(node[1]) != 3 or not isinstance(node[1][2], str) or not meta.GUID.match(node[1][2]):
+		return False
+	return isinstance(node[2], str) and bool(node[2]) and not node[2].isdigit()
+
+
+def find_identity(node):
+	"""First identity block in a header subtree, depth first."""
+	if not isinstance(node, list):
+		return None
+	if is_identity(node):
+		return node
+	for item in node:
+		found = find_identity(item)
+		if found is not None:
+			return found
+	return None
+
+
+def is_field(node):
+	"""A field is an identity block immediately followed by its type pattern."""
+	return (isinstance(node, list) and len(node) >= 3 and is_identity(node[1])
+	        and isinstance(node[2], list) and node[2] and node[2][0] == "Pattern")
+
+
+def name_of(node):
+	return node[1][2]
+
+
+def guid_of(node):
+	"""The attribute's own GUID, from its identity block.
+
+	This is what DBNames keys its `Fld` entries by, so it is how a ported column is
+	traced back to the `_FldNNN` the data actually sits in.
+	"""
+	ident = node[1]
+	head = ident[1] if len(ident) > 1 else None
+	return head[2] if isinstance(head, list) and len(head) > 2 else None
+
+
+def synonym_of(node):
+	syn = node[1][3] if len(node[1]) > 3 else None
+	return syn[2] if isinstance(syn, list) and len(syn) >= 3 else None
+
+
+def is_collection(node):
+	"""[<class guid>, <count>, member, member, ...] - attributes, dimensions, resources."""
+	return (isinstance(node, list) and len(node) > 2 and isinstance(node[0], str)
+	        and meta.GUID.match(node[0]) and isinstance(node[1], str) and node[1].isdigit())
+
+
+def decode_type(pattern, types):
+	"""['Pattern', ['S','30','1'], guid, ...] -> readable type."""
+	parts, refs = [], []
+	for item in pattern[1:]:
+		if isinstance(item, str) and meta.GUID.match(item):
+			refs.append(item)
+		elif isinstance(item, list) and item:
+			head = item[0]
+			if head == "S":
+				parts.append("string(%s)" % (item[1] if len(item) > 1 else "?"))
+			elif head == "N":
+				parts.append("number(%s,%s)" % (item[1] if len(item) > 1 else "?",
+				                                item[2] if len(item) > 2 else "0"))
+			elif head == "B":
+				parts.append("bool")
+			elif head == "D":
+				parts.append("date(%s)" % (item[1] if len(item) > 1 else "DateTime"))
+			else:
+				refs.extend(s for s in item if isinstance(s, str) and meta.GUID.match(s))
+	for guid in refs:
+		target = types.get(guid)
+		parts.append("-> %s.%s" % (target["family"], target["name"]) if target
+		             else "-> <%s>" % guid[:8])
+	return ", ".join(parts) or "?"
+
+
+def has_pattern(node):
+	if not isinstance(node, list):
+		return False
+	if node and node[0] == "Pattern":
+		return True
+	return any(has_pattern(item) for item in node)
+
+
+def tabular_section_info(node):
+	"""A tabular section is [<header>, ..., <columns collection>]: a named header that
+	carries no type of its own, followed by a collection of typed columns.
+
+	Returns (name, guid). The GUID is what DBNames keys the section's `_VT` table and
+	its `_LineNo` column by.
+	"""
+	if len(node) < 3 or not isinstance(node[0], list) or not is_collection(node[2]):
+		return None
+	if has_pattern(node[0]):
+		return None
+	ident = find_identity(node[0])
+	if ident is None:
+		return None
+	head = ident[1] if len(ident) > 1 else None
+	guid = head[2] if isinstance(head, list) and len(head) > 2 else None
+	return ident[2], guid
+
+
+def tabular_section_name(node):
+	found = tabular_section_info(node)
+	return found[0] if found else None
+
+
+def collect(node, section, collection, types, fields, section_guid=None):
+	if not isinstance(node, list):
+		return
+	if is_field(node):
+		fields.append({
+			"section": section,
+			"sectionGuid": section_guid,
+			"collection": collection,
+			"name": name_of(node),
+			"guid": guid_of(node),
+			"synonym": synonym_of(node),
+			"type": decode_type(node[2], types),
+		})
+		return
+	found = tabular_section_info(node)
+	if found:
+		section, section_guid = found
+	if is_collection(node):
+		collection = node[0]
+		node = node[2:]
+	for item in node:
+		collect(item, section, collection, types, fields, section_guid)
+
+
+def enum_values(tree, object_name):
+	"""Enum members carry no type pattern, so they are plain identity blocks."""
+	values = []
+	def walk(node):
+		if not isinstance(node, list):
+			return
+		if is_identity(node):
+			if node[2] != object_name and node[2] not in values:
+				values.append(node[2])
+			return
+		for item in node:
+			walk(item)
+	walk(tree)
+	return values
+
+
+def load_json(name):
+	with codecs.open(os.path.join(OUT, name), "r", "utf-8") as f:
+		return json.load(f)
+
+
+def fields_of(name, objects, types):
+	guid = next((o["guid"] for o in objects if o.get("name") == name), None)
+	if not guid:
+		return None, None
+	text = meta.load(guid)
+	if text is None:
+		return guid, None
+	fields = []
+	collect(meta.parse(text), None, None, types, fields)
+	return guid, fields
+
+
+def main():
+	objects = load_json("objects.json")
+	types = load_json("typemap.json")
+	report = {r["name"]: r for r in load_json("report.json")}
+
+	if sys.argv[1] == "--model":
+		out_path, names = sys.argv[2], sys.argv[3:]
+		lines = ["# Transport & shipping contour - extracted model", "",
+		         "Generated from the `%s` MS SQL infobase without 1C software."
+	         % os.environ.get("DF1C_DB", "source"), ""]
+		for name in names:
+			guid, fields = fields_of(name, objects, types)
+			row = report.get(name, {})
+			if fields is None:
+				lines += ["## %s *(not found)*" % name, ""]
+				continue
+			lines += ["## %s.%s - %s" % (row.get("family", "?"), name, row.get("synonym") or ""),
+			          "",
+			          "`%s` - %s rows, %s child rows" % (
+				          row.get("physical"),
+				          "{:,}".format(row.get("rows") or 0),
+				          "{:,}".format(row.get("childRows") or 0)), ""]
+			if not fields:
+				values = enum_values(meta.parse(meta.load(guid)), name)
+				if values:
+					lines += ["Values: " + ", ".join(values), ""]
+				continue
+			sections = [None] + sorted({f["section"] for f in fields if f["section"]})
+			for section in sections:
+				chunk = [f for f in fields if f["section"] == section]
+				if not chunk:
+					continue
+				chunk.sort(key=lambda f: ROLE_ORDER.index(ROLE[f["collection"]])
+				           if ROLE.get(f["collection"]) in ROLE_ORDER else 9)
+				lines += ["**%s**" % (section or "header"), "",
+				          "| role | field | synonym | type |", "|---|---|---|---|"]
+				for f in chunk:
+					lines.append("| %s | %s | %s | %s |" % (
+						ROLE.get(f["collection"], "?"), f["name"],
+						f["synonym"] or "", f["type"]))
+				lines.append("")
+		with codecs.open(out_path, "w", "utf-8") as f:
+			f.write("\n".join(lines))
+		print("wrote %s (%d objects)" % (out_path, len(names)))
+		return
+
+	name = sys.argv[1]
+	guid, fields = fields_of(name, objects, types)
+	if fields is None:
+		print("no such object: %s" % name)
+		return
+	print("%s (%s)  fields=%d\n" % (name, guid, len(fields)))
+	for f in fields:
+		print("   %-10s %-22s %-34s %-28s %s"
+		      % (ROLE.get(f["collection"], (f["collection"] or "")[:8]),
+		         f["section"] or "", f["name"], f["synonym"] or "", f["type"]))
+
+
+if __name__ == "__main__":
+	main()