Start adding support for lock files.

utils/pub/lock_file.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+#library('lock_file');
+
+#import('package.dart');
+#import('source_registry.dart');
+#import('utils.dart');
+#import('version.dart');
+#import('yaml/yaml.dart');
+
+/**
+ * A parsed and validated `pubspec.lock` file.
+ */
+class LockFile {
+  /**
+   * The packages this lockfile pins.
+   */
+  Map<String, PackageId> packages;
+
+  LockFile._(this.packages);
+
+  LockFile.empty()
+    : packages = <PackageId>{};
+
+  /**
+   * Parses the lockfile whose text is [contents].
+   */
+  factory LockFile.parse(String contents, SourceRegistry sources) {
+    var packages = <PackageId>{};
+
+    if (contents.trim() == '') return new LockFile.empty();
+
+    var parsed = loadYaml(contents);
+
+    if (parsed.containsKey('packages')) {
+      var packageEntries = parsed['packages'];
+
+      packageEntries.forEach((name, spec) {
+        // Parse the version.
+        if (!spec.containsKey('version')) {
+          throw new FormatException('Package $name is missing a version.');
+        }
+        var version = new Version.parse(spec['version']);
+
+        // Parse the source.
+        if (!spec.containsKey('source')) {
+          throw new FormatException('Package $name is missing a source.');
+        }
+        var sourceName = spec['source'];
+        if (!sources.contains(sourceName)) {
+          throw new FormatException(
+              'Could not find a source named $sourceName.');
+        }
+        var source = sources[sourceName];
+
+        // Parse the description.
+        if (!spec.containsKey('description')) {
+          throw new FormatException('Package $name is missing a description.');
+        }
+        var description = spec['description'];
+        source.validateDescription(description);
+
+        var id = new PackageId(source, version, description);
+
+        // Validate the name.
+        if (name != id.name) {

[Jennifer Messerly, 2012/06/06 00:23:52]

How could this happen? It sounds like this means description got mismatched from
the name?

Might be worth giving more information in the exception message, if the message
is intended for end users, so they know what went wrong and how to fix it.

[Bob Nystrom, 2012/06/06 20:44:48]

Exactly right. This shouldn't occur in practice, but it doesn't hurt to sanity
check it. The "description" is a source-specific string that the source
interprets to uniquely identify a package. For example, it will be a git URL if
the source is git. Given that, the source is also responsible for yielding a
nice short package name.

The lock file lists the packages by the short name and includes the description.
So this just sanity checks that those aren't out of sync.
This shouldn't happen much in practice. The lock file will be generated
automatically by pub (it's the result of solving the version constraints) and
then parsed back in by it. But users could always hand-edit it or do something
weird, so it's good to validate it.

If we find that people hit this error, I'll definitely do better
error-reporting. I consider error-reporting a core piece of pub's UI, given that
it's a command line app that heavily works with files users hand-edit.

+          throw new FormatException(
+            "Package name $name doesn't match ${id.name}.");
+        }
+
+        packages[name] = id;
+      });
+    }
+
+    return new LockFile._(packages);
+  }
+}